Quick Start Guide for retrieving the documents using Shell MarketHub Document API

This guide helps you to fetch the USF documents from Shell MarketHub2.0 platform, which consist of the SMH API Service called Document API.

The Document API uses the OAuth2 authorization code grant type to obtain permission for you from Shell to retrieve the following documents:

• Rack/Contract Price
• Invoice Documents
• Settlement Documents - Daily Settlement Advice (DSA), Deferred Tax (DFT), Statement of Account (SOA)

Retrieving documents from SMH 2.0 is a two step process as mentioned below:

1. Your application sends the OAuth 2.0 authentication request to Shell's Authentication server with the Client Credentials (Client ID and Client Secret) provided by Shell to generate a time sensivite accessToken.

2. After the authentication is successful, your applications sends a document retrieval request to Shell MarketHub2.0 system using document API

Authentication

SMH Document API is secured by OAuth 2.0. It uses Client Credentials grant Type to allow the API consumer to access data. The end to end process is illustrated in the sequence diagram below :

Below is the sequence followed:

1. Your applications makes a request to Shell's Authentication Server (OAuth Authentication) to obtain Access token.
2. Your application then uses the Access token, API Service Account Credentials (Client ID, Client Secret, apiKey) and RequestId to make requests to SMH 2.0 Document API via Shell API Management Gateway.

Base URLs

Get an Access Token

Once you receive the Client ID and Client Secret, next step is to obtain an access token by making a request to {Shell Authentication Server}/as/token.oauth2 endpoint to authenticate.

Key request parameters

Sample request

curl --location 'https://sso-dev.shell.com/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=***********' \
--data-urlencode 'client_secret=**********' \
--data-urlencode 'grant_type=client_credentials'

Sample response

{
    "access_token": "***********",
    "token_type": "Bearer",
    "expires_in": 899
}

Note: The Access Token is valid for 899s (15 mins).

Invoke Document API for Rack/Contract Price

Key Request Parameters

Sample Request

curl --location 'https://api-dev.shell.com/commerce/usfuels/v1/document' \
--header 'RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
--header 'client_secret: ***********' \
--header 'client_id: ***********' \
--header 'apiKey: ***********' \
--header 'Referrer-Policy: no-referrer' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "documentType": "rackPrice",
    "outputFormat": "xml",
    "soldTo": "********", 

    "fromDate": "20250214",
    "toDate": "20250315"
}'

Sample Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NAXML-FuelsDoc>
    <TransmissionHeader>
        <TransmissionId>************</TransmissionId>
        <TransmissionDate>2025-05-17</TransmissionDate>
        <TransmissionTime>12:38</TransmissionTime>
        <TransmissionStatus actionType="original"/>
    </TransmissionHeader>
    <Parties>
        <Supplier>
            <Name ident="************" identType="DUNS">SHELL</Name>
            <City>Houston</City>
            <State>TX</State>
        </Supplier>
        <Buyer>
            <Name classOfTrade="Wholesale" ident="************" identType="CustomerNumber">TEST ABC</Name>
            <FuelPriceInfo>
                <Terminal>
                    <Name ident="************" identType="PlantNumber">TEST</Name>
                    <City>INDIANAPOLIS</City>
                    <FuelProduct>
                        <EffectiveDate>20250313</EffectiveDate>
                        <EffectiveTime>1800</EffectiveTime>
                        <FuelProductId identType="************">************</FuelProductId>
                        <Price>************</Price>
                        <NetChange>************</NetChange>
                    </FuelProduct>
                </Terminal>
            </FuelPriceInfo>
        </Buyer>
    </Parties>
    <SaleTerms>FOB</SaleTerms>
</NAXML-FuelsDoc>

Invoke Document API for Invoice Documents

Key Request parameters

Sample Request

curl --location 'https://api-dev.shell.com/commerce/usfuels/v1/document' \
--header 'RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
--header 'client_secret: ***********' \
--header 'client_id: ***********' \
--header 'apiKey: ***********' \
--header 'Referrer-Policy: no-referrer' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "DocumentType": "invoice",
    "OutpuTFormat": "txt",
    "soldTo": "********",
    "fromDate": "20250401",
    "toDate": "20250428"


}'

Sample response

                              Shell Oil Products US
                                   Debit Note
-------------------------------------------------------------------------------
INVOICE NO: **********                                  INVOICE DATE: 03/25/2025
-------------------------------------------------------------------------------
......
.....

Invoke Document API for Settlement Documents - DSA

Key request parameters

Sample request

curl --location 'https://api-dev.shell.com/commerce/usfuels/v1/document' \
--header 'RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
--header 'client_secret: ***********' \
--header 'client_id: ***********' \
--header 'apiKey: ***********' \
--header 'Referrer-Policy: no-referrer' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--header 'Cookie: PF=6vTDSS6KmpAq5vdrbNZFEI; ROUTE=.api-f84974cb5-sqsbq' \
--data '{
    "DocumentType": "settlement",
    "OutpuTFormat": "txt",
    "payerId": "********",
    "fromDate": "20250226",
    "toDate": "20250320"
}'

Sample Response

                                Settlement Advice

                                                               Shell Oil Products US
                                     For any queries please contact Customer Service
                                         Telephone:               ******************
                                                                  Fax:  ************
                                                                http://www.shell.com

Payer Number: US16 ********
......
.....

Invoke Document API for Settlement Documents - DFT

Key Request parameters

sample request

curl --location 'https://api-test.shell.com/commerce/usfuels/v1/document' \
--header 'RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
--header 'client_secret: ***********' \
--header 'client_id: ***********' \
--header 'apiKey: ***********' \
--header 'Referrer-Policy: no-referrer' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "DocumentType": "dft",
    "OutpuTFormat": "txt",
    "payerId": "********",
    "fromDate": "20250226",
    "toDate": "20250320"
}'

sample response

204 No Content

Invoke Document API for Settlement Documents - SOA

Key request Parameters

Sample_Request

curl --location 'https://api-dev.shell.com/commerce/usfuels/v1/document' \
--header 'RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
--header 'client_secret: ***********' \
--header 'client_id: ***********' \
--header 'apiKey: ***********' \
--header 'Referrer-Policy: no-referrer' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "DocumentType": "soa",
    "OutpuTFormat": "txt",
    "payerId": "********",
    "fromDate": "20250226",
    "toDate": "20250320"
}'

Sample_Response

                     Statement of Account as of 02/28/2025

                                                            ************************
                                     For any queries please contact Customer Service
                                         Telephone:               ******************
                                                                  Fax:  ************
                                                                http://www.shell.com

Payer Number:    ****************
......
.....

Success Codes

Error Codes