Skip to content

Updating Orders

For Onward to provide insurance and handle customer claims, we need an accurate and up-to-date customer order record.

When any changes are made by your customers or staff that affect the items, shipments, or dollar value of an order you would use the API to reflect the changes in Onward.

Flow diagram

For example, when:

  • An item is added or removed from an order
  • An order is partially or fully refunded
  • Edits are made to customer or shipping information
  • etc...

Use the "Update an order" endpoint to send that information to Onward:

curl -i -X PATCH \
  'https://app.useonward.com/api/v1/orders/{shopOrderId}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_order_number": "W-94713",
    "subtotal_price": {
      "cents": 1999,
      "currency": "USD"
    },
    "total_discounts_price": {
      "cents": 599,
      "currency": "USD"
    },
    "total_shipping_price": {
      "cents": 299,
      "currency": "USD"
    },
    "total_tax_price": {
      "cents": 143,
      "currency": "USD"
    },
    "total_price": {
      "cents": 2499,
      "currency": "USD"
    },
    "financial_status": "paid",
    "customer": {
      "shop_customer_id": "7461",
      "first_name": "Sally",
      "last_name": "Loo",
      "email": "sally@example.com",
      "phone_number": "+13105551234"
    },
    "shipping_address": {
      "address1": "123 Main St",
      "address2": "Unit 50",
      "province_code": "CA",
      "city": "Los Angeles",
      "postal_code": "90210",
      "country_code": "US",
      "phone_number": "+13105551234"
    },
    "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"
        }
      }
    ]
  }'

Or when:

  • A shipment is created
  • A shipment is dispatched
  • Tracking information is updated

Use the "Create a shipment" endpoint...

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"
  }'

...and "Create a shipment event" endpoint to inform Onward:

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"
  }'
Previous page
Next page