Calculating Tax and Shipping for Shoppable Ads

Required for: API, CSV, URL, SFTP, EDI Catalog integration methods

When a shopper purchases your product through a Shoppable Ad, Rokt orchestrates the order in real time. Before the order is placed, Rokt calls your APIs to retrieve the applicable shipping rates (if desired) and tax amounts (required). Once the order is confirmed, Rokt delivers it to you via webhook for fulfillment.

The order flow for Rokt Shoppable Ads proceeds as follows:

1. Shopper selects a product and initiates checkout.
2. Rokt calls your endpoint to fetch available shipping cost and to calculate applicable tax.
3. Shopper completes payment using secure payment forwarding with you as MoR.
4. Rokt Catalog sends you an order with full order details.
5. You fulfill the order and send tracking information back.

---

Authentication

All API endpoints require the following authentication headers on every request:

Header Name	Type	Required	Description
x-api-key	string	Yes	API key provided during onboarding
x-api-secret	string	Yes	API secret provided during onboarding
Content-Type	string	Yes	Must be application/json

---

Shipping Rate API

By default, Shipping values can be set via Rokt Catalog for Brands as a flat rate for Shoppable Ads. We highly recommend offering free shipping ($0.00) as it is a strong incentive for conversion in placement. This can be set directly in Rokt Catalog for Brands.

If you want your shipping rates to be dynamic, you must expose and host this endpoint. Rokt calls your Shipping Rate endpoint during checkout to present real-time shipping options to the shopper. Provide the URL to your Rokt account manager during onboarding.

Request (Rokt → Your endpoint)

Rokt sends a request to your Shipping Rate URL with the following payload:

Request Body

Field Name	Type	Required	Description
origin	object	Yes	Warehouse/origin address
destination	object	Yes	Shopper destination address
products	array	Yes	Array of SKU and quantity
currency	string	No	Currency code, defaults to USD

origin / destination Object

Field Name	Type	Required	Description
address1	string	Yes	Primary street address
address2	string | null	No	Secondary address line
city	string	Yes	City
stateCode	string	Yes	State or province code (e.g. TX)
postalCode	string	Yes	ZIP or postal code
country	string	Yes	Country code (e.g. US)

products Array Item

Field Name	Type	Required	Description
sku	string	Yes	Product SKU
quantity	integer	Yes	Quantity ordered

Example Request

Rokt sends a POST to your Shipping Rate URL (for example https://api.yourbrand.com/rokt/shipping-rates) with the following payload:

{
  "origin": {
    "address1": "123 Warehouse St",
    "address2": null,
    "city": "Memphis",
    "stateCode": "TN",
    "postalCode": "38101",
    "country": "US"
  },
  "destination": {
    "address1": "456 Shopper Ave",
    "address2": null,
    "city": "Austin",
    "stateCode": "TX",
    "postalCode": "78701",
    "country": "US"
  },
  "products": [
    {
      "sku": "SHOE-8-BLK",
      "quantity": 1
    }
  ],
  "currency": "USD"
}

Response (Your endpoint → Rokt)

Return an array of the selected shipping rate. Rokt presents this option to the shopper at checkout:

Response Body

Field Name	Type	Description
rates	array	Array of shipping rate options
rates[].service_name	string	Display name (e.g. Standard Shipping)
rates[].service_code	string	Internal code (e.g. STANDARD)
rates[].total_price	number	Shipping cost in decimal dollars (e.g. 7.99)
rates[].currency	string	Currency code
rates[].min_delivery_date	string	Earliest delivery date (YYYY-MM-DD)
rates[].max_delivery_date	string	Latest delivery date (YYYY-MM-DD)
success	boolean	true if rates returned successfully
errorMessage	string	Present only on failure

Example Response

{
  "rates": [
    {
      "service_name": "Standard Shipping",
      "service_code": "STANDARD",
      "total_price": 7.99,
      "currency": "USD",
      "min_delivery_date": "2026-03-24",
      "max_delivery_date": "2026-03-27"
    }
  ],
  "success": true
}

備考

Prices are in decimal dollars. total_price values must be expressed as decimal numbers (e.g. 7.99 = $7.99).

Error Responses

HTTP Code	success	errorMessage
200	false	Product {sku} is not available.
401	false	Unauthorized: Invalid API key
400	false	Bad Request: products is missing.
400	false	Bad Request: shippingAddress is missing.
500	false	Unexpected error: if the error persists, please contact an administrator.

---

Tax API

You must expose and host this endpoint. Rokt calls your Tax endpoint during checkout to calculate the applicable tax for the order. Provide the URL to your Rokt account manager during onboarding.

Request (Rokt → Your endpoint)

Request Body

Field Name	Type	Required	Description
products	array	Yes	Array of SKU and quantity
shippingAddress	object	Yes	Shipping destination address

shippingAddress Object

Field Name	Type	Required	Description
address1	string	Yes	Primary street address
address2	string | null	No	Secondary address line
city	string	Yes	City
stateCode	string	Yes	State or province code (e.g. TX)
postalCode	string	Yes	ZIP or postal code

products Array Item

Field Name	Type	Required	Description
sku	string	Yes	Product SKU
quantity	integer	Yes	Quantity ordered

Example Request

Rokt sends a POST to your Tax URL (for example https://api.yourbrand.com/rokt/tax) with the following payload:

{
  "products": [
    {
      "sku": "SHOE-8-BLK",
      "quantity": 1
    }
  ],
  "shippingAddress": {
    "address1": "456 Shopper Ave",
    "city": "Austin",
    "stateCode": "TX",
    "postalCode": "78701"
  }
}

Response (Your endpoint → Rokt)

Response Body

Field Name	Type	Description
success	boolean	true if tax calculated successfully
tax	array	Per-product tax breakdown
tax[].productId	string	SKU or product identifier
tax[].taxRate	number	Tax rate as decimal (e.g. 0.0775 = 7.75%)
tax[].taxAmount	number	Tax amount in decimal dollars (e.g. 2.44)
taxTotal	number	Total tax across all products in decimal dollars
errorMessage	string	Present only on failure

Example Response

{
  "success": true,
  "tax": [
    {
      "productId": "SHOE-8-BLK",
      "taxRate": 0.0625,
      "taxAmount": 8.12
    }
  ],
  "taxTotal": 8.12
}

備考

Tax amounts are in decimal dollars. Consistent with the Shipping Rate API, taxAmount and taxTotal must be expressed as decimal numbers (e.g. 8.12 = $8.12), and taxRate as a decimal fraction (e.g. 0.0625 = 6.25%).

Error Responses

HTTP Code	success	errorMessage
200	false	Product {sku} is not available.
401	false	Unauthorized: Invalid API key
400	false	Bad Request: products is missing.
400	false	Bad Request: shippingAddress is missing.
500	false	Unexpected error: if the error persists, please contact an administrator.