Express Checkout API

❗️
Interested in offering Affirm Express Checkout?
Reach out to your Affirm Account Manager to confirm availability and for next steps on building your APIs.

Overview

Affirm Express Checkout relies on one merchant-hosted API endpoint to dynamically complete checkout within the Affirm experience: Shipping & Totals Endpoint. This endpoint enables Affirm to collect customer shipping details, present valid shipping methods, calculate taxes and totals, and return finalized order details to the merchant after loan confirmation.

By offloading address collection and checkout calculation into Affirm’s hosted flow, merchants can reduce front-end checkout complexity while retaining full control over shipping logic, pricing, and tax calculations on the backend.

Shipping & Totals endpoint types

The Shipping & Totals endpoint calculates and returns available shipping options and final order totals based on the customer’s shipping address during checkout.

Request

Headers

Header	Type	Required	Description
`X-Affirm-Signature`	`string`	Yes	Used to verify that the request is legitimately from Affirm. It contains a timestamp and an HMAC-SHA512 hash of the request body, signed with your Private API Key.
`Content-Type`	`string`	Yes	Must be set to `application/json` as the endpoint accepts and returns JSON payloads.

Body

Field	Type	Required	Description
`order_id`	`string`	Yes	Merchant identifier to reference the current checkout session. Note you are still expected to give an `order_id` post-loan confirmation.
`currency`	`string`	Yes	Three-letter ISO currency code in uppercase.
`shipping`	`ShippingBilling.Address`	Yes	Shipping Address.

`ShippingBilling.Address`

Field	Type	Required	Description
`line1`	`string`	Yes	Address line 1 (e.g., street, PO Box, or company name).
`line2`	`string`	No	Address line 2 (e.g., apartment, suite, unit, or building).
`city`	`string`	Yes	City, district, suburb, town, or village.
`state`	`string`	Yes	State, county, province, or region.
`zipcode`	`string`	Yes	ZIP or postal code.
`country`	`string`	Yes	Two-letter country code (ISO 3166-1 alpha-2).

HTTP 200 Response

Body

Field	Type	Required	Description
`order_id`	`string`	Yes	Merchant identifier to reference the current checkout session. Note you are still expected to give an `order_id` post-loan confirmation.
`currency`	`string`	Yes	Three-letter ISO currency code in uppercase.
`subtotal`	`integer`	Yes	Total cost amount of the items in the cart, excluding any taxes or shipping fees, in the minor currency unit of the specified ISO currency code. Example: 100 cents to charge $1.00
`shipping_options`	`Array<Object> (ShippingOption)`	Yes	The available shipping options along with their associated order totals.

`ShippingOption`

Field	Type	Required	Description
`shipping_type`	`string`	Yes	Yes A unique, merchant-generated identifier for the shipping option. This value is used to map the customer’s selection to your internal fulfillment records and must remain persistent throughout the session. Please ensure that each shipping option has its own unique `shipping_type` value. Examples: “Shipping_ups_123”, “Shipping_fedex_456”, “instore_pickup_789”.
`shipping_label`	`string`	Yes	The shipping method label displayed to the user. Example: “Standard Shipping (7-10 Days)')”
`shipping_amount`	`integer`	Yes	The cost of shipping in the minor currency unit of the specified ISO currency code. Example: 100 cents to charge $1.00
`tax_amount`	`integer`	Yes	The total tax amount in the minor currency unit of the specified ISO currency code. Example: 100 cents to charge $1.00
`total`	`integer`	Yes	The total amount of the checkout in the minor currency unit of the specified ISO currency code. Example: 100 cents to charge $1.00

HTTP 422 Response

Body

Field	Type	Required	Description
`errors`	`Array<Object> (Error)`	Yes	An array of one or more error objects describing why the request could not be processed. Must contain at least one element.

`Error`

Field	Type	Required	Description
`error_code`	`enum`	Yes	One of the predefined Affirm error codes.
`message`	`string`	Yes	A description of the error.
`fields`	`string[]`	No	The request payload property that caused the error.

`error_code Enum`

Error code	Description
`UNSUPPORTED_SHIPPING_ZONE`	Used when the address is valid but the merchant does not ship to that region (e.g., Hawaii/Alaska).
`INVALID_SHIPPING_ADDRESS`	The provided address does not exist or is malformed.
`ORDER_NOT_FOUND`	The `order_id` passed in the request does not match an active session or cart in the merchant's system.
`CURRENCY_MISMATCH`	The merchant's system does not support the currency specified in the request (e.g., merchant only supports CAD but receives USD).
`INVENTORY_UNAVAILABLE`	Between initiating checkout and calculating totals, items in the items array have gone out of stock.
`SHIPPING_METHOD_UNAVAILABLE`	No valid shipping options can be generated for the requested address (e.g., oversized items to a remote area).
`INTERNAL_SERVER_ERROR`	A catch-all for unexpected merchant-side backend failures or database timeouts during the calculation.