Create / Update an Order

put

https://api.helloextend.com/orders

This endpoint allows merchants to create a new order or update an existing order. New orders will be created if the Transaction ID value provided does not already exist on an order for the merchant’s store. If the Transaction ID value provided exists on an order for the merchant’s store, updates will be made according to the data included in the API request.

Please find instructions below on how to perform certain updates on existing orders:

To refund all contracts associated to an order, include the order status of 'refunded' in the request. This will refund all contract line items and cancel any line items that are not associated to a contract.
To refund or cancel line items on an order, either send a reduced quantity for the line item or do not include the line item in the request. This will refund all contracts for the line item or cancel the line item if it is not associated to a contract.
To refund a single product protection contract only on an order, do not include a plan container with the line item that corresponds to the contract that needs to be refunded.
To add line items to an order, increment the quantity of the existing line or include a new line item with a unique Line Item Transaction ID in the request.
To maintain an accurate number of fulfilled products on order line items, always send the correct value of fulfilled products in Fulfilled Quantity field in the request.
To maintain shipment records on orders, our service will use the Tracking ID in each record to determine if shipments should be added, updated, or removed from the order.
When line items that are covered by a shipping protection contract are canceled or refunded, our system will automatically attempt to issue a partial refund for the contract. The API response will display products that were removed from coverage and the new contract premium if the partial refund is processed successfully.

Body Params

analytics

object

Contains additional information about an order that helps with reporting and analytics.

discounts

array of objects

Array of discounts applied to the order

discounts

cartId

string

Unique identifier for the cart in the merchant’s system.

currency

string

enum

required

customer

object

required

The customer who made a purchase.

discountAmountTotal

integer

0 to 9007199254740991

Total discount amount for the order.

formId

string

This field is used for Jewelry orders where merchants need to provide additional reporting and analytics context for the order.

isHistorical

boolean

Denotes whether or not the order was created through the historical orders endpoint.

isTest

boolean

Flag that tracks whether the transaction was created as a test or not. NOTE - This is defaulted to false and should be used only under special circumstances.

merchantCustomerId

string

Unique identifier for the customer in the merchant’s system.

poNumber

string

Purchase order number in merchant's system.

productCostTotal

integer

0 to 9007199254740991

Total purchase cost of all products (and their quantities) included on the order, not including shipping, tax, or discount amounts.

resellerMerchant

object

Data related to reseller merchants. This can be used by merchants when different store information from the merchant’s Extend store must be displayed to customers.

customerReturnPolicyId

string

Unique identifier for the return policy associated with this order.

saleOrigin

object

Critical sales data indicated where the order was processed (e.g. web, store) that allows Extend to optimize warranty attach rates and improve program performance.

shippingCostTotal

integer

0 to 9007199254740991

The total shipping cost for the order.

shippingTaxCostTotal

integer

0 to 9007199254740991

Total shipping tax amount for the order.

status

string

enum

Status of the order in Extend’s system. Note - A status of refunded can be included in the request to indicate the entire order has been refunded. This is only available in the Orders Upsert endpoint.

Allowed:

storeId

string

required

Unique identifier for merchant’s store in Extend’s system.

storeName

string

Merchant's store name in Extend.

taxCostTotal

integer

0 to 9007199254740991

The total tax cost for the order.

total

integer

≤ 9007199254740991

Total cost of the order, including all product purchase costs, shipping, taxes, discounts, and any other amounts. This should reflect the total amount that the customer paid for the order.

transactionDate

integer

≤ 9007199254740991

Order’s transaction date. No default will be set if no value is provided.

transactionId

string

required

Unique identifier provided by merchant for transaction associated to Extend order.

waitPeriod

number

≤ 9007199254740991

Number of days that should be applied before a contract is created from an order. This is typically used to confirm a payment was successfully captured or to wait a period of time to ensure a transaction isn’t fraudulent. NOTE - This field accepts the number of days and does not have to be a whole number (e.g. half a day can be sent as 0.5).

lineItems

array

required

length ≤ 500

Order Line Items should include all items purchased on the order regardless of contract status. Lines will automatically be categorize based on the properties included in the request.

Contract

include Product and Plan objects
triggers creation of a product protection contract

Lead

include Product object with a warrantable product and omit Plan object
triggers creation of a lead token

Shipping Protection Contract

include Shipment Info object and Quote ID property
triggers creation of a shipping protection contract

Non-Warrantable

Include Product object with a non-warrantable product

lineItems*

Headers

Content-Type

string

required

Used to indicate the original media type of the resource (prior to any content encoding applied for sending).

X-Extend-Access-Token

string

required

An Extend private API key used to authenticate requests.

X-Idempotency-Key

uuid

required

Randomly generated string (recommended v4 UUID) to ensure idempotent requests. See Idempotent Requests.

string

required

Indicates which content types, expressed as MIME types, the client is able to understand, as well as identifies which API version to use in the request.

Responses

201Successful creation of the order.

404The specified resource was not found

422Unprocessable entity

500Internal server error