Update an order

Request

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

Security

api_key

Path

shopOrderIdstringrequired

Your unique ID for the Order (the same shop_order_id you sent when creating it)

Content-Typestringrequired

Content-Type must be application/json

Example:application/json

Acceptstringrequired

Accept must be application/json

Example:application/json

Bodyapplication/jsonrequired

shop_order_numberstringrequired

The Order Number as presented to the customer

Example:"W-94713"

subtotal_priceobject(Money)required

Order subtotal in customer's currency

total_discounts_priceobject(Money)required

Sum of applied discounts in customer's currency

total_shipping_priceobject(Money)required

Shipping amount in customer's currency

total_tax_priceobject(Money)required

Total tax in customer's currency

total_priceobject(Money)required

Order total in customer's currency

financial_statusstringrequired

Enum:"pending""paid""refunded""voided"

Example:"paid"

customerobject(Customer)required

At least one of first_name, last_name, email or phone_number is required.

shipping_addressobject(Address)required

line_itemsArray of objects(LineItem)required

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": 1299,
      "currency": "USD"
    },
    "total_discounts_price": {
      "cents": 1299,
      "currency": "USD"
    },
    "total_shipping_price": {
      "cents": 1299,
      "currency": "USD"
    },
    "total_tax_price": {
      "cents": 1299,
      "currency": "USD"
    },
    "total_price": {
      "cents": 1299,
      "currency": "USD"
    },
    "financial_status": "paid",
    "customer": {
      "shop_customer_id": "6072418623",
      "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": 1299,
          "currency": "USD"
        },
        "total_price": {
          "cents": 1299,
          "currency": "USD"
        },
        "total_price_presentment": {
          "cents": 1299,
          "currency": "USD"
        },
        "quantity": 2,
        "image_url": "https://placecats.com/neo/300/200.png",
        "grams": 24,
        "is_protected": true,
        "requires_shipping": true,
        "refunded_quantity": 1,
        "refunded_price": {
          "cents": 1299,
          "currency": "USD"
        },
        "refunded_price_presentment": {
          "cents": 1299,
          "currency": "USD"
        }
      }
    ]
  }'

Responses

Order updated successfully

Bodyapplication/json

shop_order_idstringrequired

Your unique identifier for the Order. Must be unique across your orders and stable over time — Onward uses it to look up and de-duplicate orders, so the same value must always refer to the same order.

Example:"18282"

shop_order_numberstringrequired

The Order Number as presented to the customer

Example:"W-94713"

lookup_keystring

Onward's identifier for this Order. Use it to deep-link a customer into the start-a-claim flow at https://app.useonward.com/inquiries/start?uuid={lookup_key}.

Example:"fa524f69d568a1b2c3d4e5f6"

subtotal_priceobject(Money)required

Order subtotal in shop's currency

subtotal_price_presentmentobject(Money)

Order subtotal in customer's currency

total_discounts_priceobject(Money)required

Sum of applied discounts in shop's currency

total_discounts_price_presentmentobject(Money)

Sum of applied discounts in customer's currency

total_shipping_priceobject(Money)required

Shipping amount in shop's currency

total_shipping_price_presentmentobject(Money)

Shipping amount in customer's currency

total_tax_priceobject(Money)required

Total tax in shop's currency

total_tax_price_presentmentobject(Money)

Total tax in customer's currency

total_priceobject(Money)required

Order total in shop's currency

total_price_presentmentobject(Money)

Order total in customer's currency

protection_paidobject(Money)

Protection paid for this order by the customer

amount_protectedobject(Money)

Sum of shippable line items that are being protected in shop's currency

amount_protected_presentmentobject(Money)

Sum of shippable line items that are being protected in customer's currency

created_atstring, (date-time)required

When the order was placed in your e-comm platform. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing Z (as in the example); timezone offsets such as -08:00 are also accepted.

Example:"2024-11-26T17:32:28Z"

financial_statusstring(FinancialStatus)required

The order's financial status. Orders synced from your platform may carry statuses beyond the four accepted when creating or updating an order.

Enum:"pending""authorized""partially_paid""paid""partially_refunded""refunded""voided"

Example:"paid"

source_namestring

Where the order was sold, as sent on creation. Reads API for orders created without one.

Example:"phone"

customerobject(CustomerWithRewards)required