Skip to content

Onward API (1.0.0)

Download OpenAPI description
onward.json
onward.yaml
Overview
E-mail
help@useonward.com
Terms of Service
Languages
Servers
https://app.useonward.com/api/v1/

Orders

Your customers orders, including the information necessary for Onward to insure and handle claims.

Operations

Shipments

Physical shipments of items within an order and their tracking events.

Operations

Create a shipment

Request

When a you ship items for an order, create that shipment in Onward.

Security
api_key
Headers
Content-Typestringrequired

Content-Type must be application/json

Example: application/json
Acceptstringrequired

Accept must be application/json

Example: application/json
Bodyapplication/jsonrequired
shop_shipment_idstringrequired

Your ID for the Shipment

Example: "3712"
shop_order_idstringrequired

Your ID for the Order this Shipment relates to

Example: "18282"
tracking_numberstringrequired

Courier tracking number

Example: "780371515850"
tracking_urlstring

URL to courier tracking page

Example: "https://www.fedex.com/wtrk/track/?trknbr=780371515850"
tracking_companystringrequired

Courier name

Example: "DHL Express"
line_itemsArray of objects(LineItem)required

The order line items included in this shipment

line_items[].​shop_line_item_idstringrequired

Your ID for the Line Item

Example: "816721"
line_items[].​shop_product_idstringrequired

Your ID for the product

Example: "142"
line_items[].​shop_variant_idstringrequired

Your ID or SKU for the variant

Example: "7261"
line_items[].​namestringrequired

Name for the product and variant purchased

Example: "Cool T-shirt - Red"
line_items[].​unit_priceanyrequired

Item price in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​total_priceanyrequired

Line item total in order's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​total_price_presentmentany

Line item total in customer's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​quantityinteger(int32)required
Example: 2
line_items[].​image_urlstring(url)required

URL to an image of the item

Example: "https://placecats.com/neo/300/200.png"
line_items[].​gramsinteger(int32)required

Weight of the item in grams

Example: 24
line_items[].​is_insuredbooleanrequired

Whether the item should be insured by Onward (generally you should set this to true for shippable items and false for digital items). Requires purchase token and amount insured in the Order.

Example: true
line_items[].​refunded_quantityinteger(int32)

Number of items refunded (for full or partial refunds)

Example: 1
line_items[].​refunded_priceany

Total refunded amount in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​refunded_price_presentmentany

Total refunded amount in customer's currency

Example: {"cents":500,"currency":"USD"}
created_atstring(date-time)required

When the shipment was created in your e-comm platform

Example: "2024-11-26T17:32:28Z"
curl -i -X POST \
  https://app.useonward.com/api/v1/shipments \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_shipment_id": "3712",
    "shop_order_id": "18282",
    "tracking_number": "780371515850",
    "tracking_url": "https://www.fedex.com/wtrk/track/?trknbr=780371515850",
    "tracking_company": "DHL Express",
    "line_items": [
      {
        "shop_line_item_id": "816721",
        "shop_product_id": "142",
        "shop_variant_id": "7261",
        "name": "Cool T-shirt - Red",
        "unit_price": {
          "cents": 500,
          "currency": "USD"
        },
        "total_price": {
          "cents": 1000,
          "currency": "USD"
        },
        "total_price_presentment": {
          "cents": 1000,
          "currency": "USD"
        },
        "quantity": 2,
        "image_url": "https://placecats.com/neo/300/200.png",
        "grams": 24,
        "is_insured": true,
        "refunded_quantity": 1,
        "refunded_price": {
          "cents": 500,
          "currency": "USD"
        },
        "refunded_price_presentment": {
          "cents": 500,
          "currency": "USD"
        }
      }
    ],
    "created_at": "2024-11-26T17:32:28Z"
  }'

Responses

Shipment created successfully

Bodyapplication/json
shop_shipment_idstringrequired

Your ID for the Shipment

Example: "3712"
shop_order_idstringrequired

Your ID for the Order this Shipment relates to

Example: "18282"
tracking_numberstringrequired

Courier tracking number

Example: "780371515850"
tracking_urlstring

URL to courier tracking page

Example: "https://www.fedex.com/wtrk/track/?trknbr=780371515850"
tracking_companystringrequired

Courier name

Example: "DHL Express"
line_itemsArray of objects(LineItem)required

The order line items included in this shipment

line_items[].​shop_line_item_idstringrequired

Your ID for the Line Item

Example: "816721"
line_items[].​shop_product_idstringrequired

Your ID for the product

Example: "142"
line_items[].​shop_variant_idstringrequired

Your ID or SKU for the variant

Example: "7261"
line_items[].​namestringrequired

Name for the product and variant purchased

Example: "Cool T-shirt - Red"
line_items[].​unit_priceanyrequired

Item price in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​total_priceanyrequired

Line item total in order's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​total_price_presentmentany

Line item total in customer's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​quantityinteger(int32)required
Example: 2
line_items[].​image_urlstring(url)required

URL to an image of the item

Example: "https://placecats.com/neo/300/200.png"
line_items[].​gramsinteger(int32)required

Weight of the item in grams

Example: 24
line_items[].​is_insuredbooleanrequired

Whether the item should be insured by Onward (generally you should set this to true for shippable items and false for digital items). Requires purchase token and amount insured in the Order.

Example: true
line_items[].​refunded_quantityinteger(int32)

Number of items refunded (for full or partial refunds)

Example: 1
line_items[].​refunded_priceany

Total refunded amount in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​refunded_price_presentmentany

Total refunded amount in customer's currency

Example: {"cents":500,"currency":"USD"}
created_atstring(date-time)required

When the shipment was created in your e-comm platform

Example: "2024-11-26T17:32:28Z"
Response
application/json
{
  "shop_shipment_id": "3712",
  "shop_order_id": "18282",
  "tracking_number": "780371515850",
  "tracking_url": "https://www.fedex.com/wtrk/track/?trknbr=780371515850",
  "tracking_company": "DHL Express",
  "line_items": [
    { … }
  ],
  "created_at": "2024-11-26T17:32:28Z"
}

Update a shipment

Request

When shipment details change in your e-comm platform, update the shipment in Onward.

Security
api_key
Path
shopShipmentIdstringrequired

Your ID for the Shipment

Headers
Content-Typestringrequired

Content-Type must be application/json

Example: application/json
Acceptstringrequired

Accept must be application/json

Example: application/json
Bodyapplication/jsonrequired
shop_shipment_idstringrequired

Your ID for the Shipment

Example: "3712"
shop_order_idstringrequired

Your ID for the Order this Shipment relates to

Example: "18282"
tracking_numberstringrequired

Courier tracking number

Example: "780371515850"
tracking_urlstring

URL to courier tracking page

Example: "https://www.fedex.com/wtrk/track/?trknbr=780371515850"
tracking_companystringrequired

Courier name

Example: "DHL Express"
line_itemsArray of objects(LineItem)required

The order line items included in this shipment

line_items[].​shop_line_item_idstringrequired

Your ID for the Line Item

Example: "816721"
line_items[].​shop_product_idstringrequired

Your ID for the product

Example: "142"
line_items[].​shop_variant_idstringrequired

Your ID or SKU for the variant

Example: "7261"
line_items[].​namestringrequired

Name for the product and variant purchased

Example: "Cool T-shirt - Red"
line_items[].​unit_priceanyrequired

Item price in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​total_priceanyrequired

Line item total in order's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​total_price_presentmentany

Line item total in customer's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​quantityinteger(int32)required
Example: 2
line_items[].​image_urlstring(url)required

URL to an image of the item

Example: "https://placecats.com/neo/300/200.png"
line_items[].​gramsinteger(int32)required

Weight of the item in grams

Example: 24
line_items[].​is_insuredbooleanrequired

Whether the item should be insured by Onward (generally you should set this to true for shippable items and false for digital items). Requires purchase token and amount insured in the Order.

Example: true
line_items[].​refunded_quantityinteger(int32)

Number of items refunded (for full or partial refunds)

Example: 1
line_items[].​refunded_priceany

Total refunded amount in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​refunded_price_presentmentany

Total refunded amount in customer's currency

Example: {"cents":500,"currency":"USD"}
created_atstring(date-time)required

When the shipment was created in your e-comm platform

Example: "2024-11-26T17:32:28Z"
curl -i -X PATCH \
  'https://app.useonward.com/api/v1/shipments/{shopShipmentId}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_shipment_id": "3712",
    "shop_order_id": "18282",
    "tracking_number": "780371515850",
    "tracking_url": "https://www.fedex.com/wtrk/track/?trknbr=780371515850",
    "tracking_company": "DHL Express",
    "line_items": [
      {
        "shop_line_item_id": "816721",
        "shop_product_id": "142",
        "shop_variant_id": "7261",
        "name": "Cool T-shirt - Red",
        "unit_price": {
          "cents": 500,
          "currency": "USD"
        },
        "total_price": {
          "cents": 1000,
          "currency": "USD"
        },
        "total_price_presentment": {
          "cents": 1000,
          "currency": "USD"
        },
        "quantity": 2,
        "image_url": "https://placecats.com/neo/300/200.png",
        "grams": 24,
        "is_insured": true,
        "refunded_quantity": 1,
        "refunded_price": {
          "cents": 500,
          "currency": "USD"
        },
        "refunded_price_presentment": {
          "cents": 500,
          "currency": "USD"
        }
      }
    ],
    "created_at": "2024-11-26T17:32:28Z"
  }'

Responses

Shipment updated successfully

Bodyapplication/json
shop_shipment_idstringrequired

Your ID for the Shipment

Example: "3712"
shop_order_idstringrequired

Your ID for the Order this Shipment relates to

Example: "18282"
tracking_numberstringrequired

Courier tracking number

Example: "780371515850"
tracking_urlstring

URL to courier tracking page

Example: "https://www.fedex.com/wtrk/track/?trknbr=780371515850"
tracking_companystringrequired

Courier name

Example: "DHL Express"
line_itemsArray of objects(LineItem)required

The order line items included in this shipment

line_items[].​shop_line_item_idstringrequired

Your ID for the Line Item

Example: "816721"
line_items[].​shop_product_idstringrequired

Your ID for the product

Example: "142"
line_items[].​shop_variant_idstringrequired

Your ID or SKU for the variant

Example: "7261"
line_items[].​namestringrequired

Name for the product and variant purchased

Example: "Cool T-shirt - Red"
line_items[].​unit_priceanyrequired

Item price in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​total_priceanyrequired

Line item total in order's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​total_price_presentmentany

Line item total in customer's currency

Example: {"cents":1000,"currency":"USD"}
line_items[].​quantityinteger(int32)required
Example: 2
line_items[].​image_urlstring(url)required

URL to an image of the item

Example: "https://placecats.com/neo/300/200.png"
line_items[].​gramsinteger(int32)required

Weight of the item in grams

Example: 24
line_items[].​is_insuredbooleanrequired

Whether the item should be insured by Onward (generally you should set this to true for shippable items and false for digital items). Requires purchase token and amount insured in the Order.

Example: true
line_items[].​refunded_quantityinteger(int32)

Number of items refunded (for full or partial refunds)

Example: 1
line_items[].​refunded_priceany

Total refunded amount in order's currency

Example: {"cents":500,"currency":"USD"}
line_items[].​refunded_price_presentmentany

Total refunded amount in customer's currency

Example: {"cents":500,"currency":"USD"}
created_atstring(date-time)required

When the shipment was created in your e-comm platform

Example: "2024-11-26T17:32:28Z"
Response
application/json
{
  "shop_shipment_id": "3712",
  "shop_order_id": "18282",
  "tracking_number": "780371515850",
  "tracking_url": "https://www.fedex.com/wtrk/track/?trknbr=780371515850",
  "tracking_company": "DHL Express",
  "line_items": [
    { … }
  ],
  "created_at": "2024-11-26T17:32:28Z"
}

Create a shipment event

Request

When a shipment status changes (e.g. it is shipped or out for delivery), notify Onward of that event.

Security
api_key
Path
shopShipmentIdstringrequired

Your ID for the Shipment

Headers
Content-Typestringrequired

Content-Type must be application/json

Example: application/json
Acceptstringrequired

Accept must be application/json

Example: application/json
Bodyapplication/jsonrequired
shop_shipment_event_idstringrequired

Your ID for the Shipment

Example: "817391"
statusstringrequired
Enum"label_printed""label_purchased""attempted_delivery""ready_for_pickup""carrier_picked_up""confirmed""in_transit""out_for_delivery""delivered""delayed"
Example: "in_transit"
messagestring
estimated_delivery_atstring(date-time)
Example: "2024-11-26T17:32:28Z"
created_atstring(date-time)required

When the event occurred in your e-comm platform

Example: "2024-11-26T17:32:28Z"
curl -i -X POST \
  'https://app.useonward.com/api/v1/shipments/{shopShipmentId}/events' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_shipment_event_id": "817391",
    "status": "in_transit",
    "message": "string",
    "estimated_delivery_at": "2024-11-26T17:32:28Z",
    "created_at": "2024-11-26T17:32:28Z"
  }'

Responses

Shipment event created successfully

Bodyapplication/json
shop_shipment_event_idstringrequired

Your ID for the Shipment

Example: "817391"
statusstringrequired
Enum"label_printed""label_purchased""attempted_delivery""ready_for_pickup""carrier_picked_up""confirmed""in_transit""out_for_delivery""delivered""delayed"
Example: "in_transit"
messagestring
estimated_delivery_atstring(date-time)
Example: "2024-11-26T17:32:28Z"
created_atstring(date-time)required

When the event occurred in your e-comm platform

Example: "2024-11-26T17:32:28Z"
Response
application/json
{
  "shop_shipment_event_id": "817391",
  "status": "in_transit",
  "message": "string",
  "estimated_delivery_at": "2024-11-26T17:32:28Z",
  "created_at": "2024-11-26T17:32:28Z"
}

Quotes

Insurance quotes for customers during checkout.

Operations