Add protection to an existing order

Request

If the customer did not purchase protection during checkout, you can merchant-protect an order after-the-fact with this endpoint. Note: it is very important that you verify the status code of this request as not every order is eligible for protection.

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

curl -i -X PATCH \
  'https://app.useonward.com/api/v1/orders/{shopOrderId}/add_protection' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Protection added 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

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

shipping_addressobject(Address)required

line_itemsArray of objects(LineItem)required

Response

{
  "shop_order_id": "18282",
  "shop_order_number": "W-94713",
  "lookup_key": "fa524f69d568a1b2c3d4e5f6",
  "subtotal_price": {
    "cents": 1299,
    "currency": "USD"
  },
  "subtotal_price_presentment": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_discounts_price": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_discounts_price_presentment": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_shipping_price": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_shipping_price_presentment": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_tax_price": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_tax_price_presentment": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_price": {
    "cents": 1299,
    "currency": "USD"
  },
  "total_price_presentment": {
    "cents": 1299,
    "currency": "USD"
  },
  "protection_paid": {
    "cents": 1299,
    "currency": "USD"
  },
  "amount_protected": {
    "cents": 1299,
    "currency": "USD"
  },
  "amount_protected_presentment": {
    "cents": 1299,
    "currency": "USD"
  },
  "created_at": "2024-11-26T17:32:28Z",
  "financial_status": "paid",
  "source_name": "phone",
  "customer": {
    "shop_customer_id": "6072418623",
    "first_name": "Sally",
    "last_name": "Loo",
    "email": "sally@example.com",
    "phone_number": "+13105551234",
    "rewards": [ … ]
  },
  "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": [
    { … }
  ]
}