HomeGetting StartedSolutionsPlatformsGlobal Integration
DocsRecipesAPI referenceChangelogAPI ReferenceRecipesChangelog
HomeGetting StartedSolutionsPlatformsGlobal IntegrationLog In
Docs
Start typing to search…

Set Up Express Checkout

Follow these steps to set up Affirm Express Checkout, including checkout configuration, shipping options, and total calculations.

Country Availability

USA USA
❗️

Interested in offering Affirm Express Checkout?

Reach out to your Affirm Account Manager to confirm availability and for next steps on building your APIs.

Prerequisites

Steps

1. Configure the Checkout object

You must configure Affirm's checkout object specifically for the Express Checkout flow:

  • Include checkout_type: "express" within the merchant object.
  • Pass the items array and all other necessary checkout attributes.
  • (Optional, but recommended) Pass a checkout order_id to trace the checkout session in your system.
  • Exclude the shipping object and the total attribute.
affirm.checkout({
  merchant: {
    checkout_type: "express", // ensure this attribute is passed for Express Checkout
    user_confirmation_url: "https://merchantsite.com/confirm",
    user_cancel_url: "https://merchantsite.com/cancel",
    public_api_key: "YOUR_PUBLIC_KEY",
    user_confirmation_url_action: "POST",
  },
  order_id: "abc123", // optional
  // exclude shipping & total attributes
  items: [{
    display_name: "Awesome Pants",
    sku: "ABC-123",
    unit_price: 10000
  }],
  // rest of checkout attributes
});

affirm.checkout.open();

2. Set up Shipping Options API endpoint

Provide a server-side API endpoint for Shipping Options that:

  • Accepts the customer's cart items and shipping address as input, and
  • Returns all valid shipping options available for the order.

See the Express Checkout API page for complete request and response payload definitions.

On user shipping address selection, Affirm sends a request with a payload similar to the following:

{
  "currency":"USD",
  // https://docs.affirm.com/developers/reference/the-item-object
  "items":[
    {
      "display_name":"Awesome Pants",
      "sku":"ABC-123",
      "unit_price":1999,
      "qty":3,
      "item_image_url":"http://merchantsite.com/images/awesome-pants.jpg",
      "item_url":"http://merchantsite.com/products/awesome-pants.html",
      "categories":[
        [
          "Apparel",
          "Pants"
        ],
        [
          "Mens",
          "Apparel",
          "Pants"
        ]
      ]
    }
  ],
  // https://docs.affirm.com/developers/reference/shipping-billing-object
  "shipping":{
    "address":{
      "line1":"325 Pacific Ave",
      "city":"San Francisco",
      "state":"CA",
      "zipcode":"94111",
      "country":"US"
    },
    "name":{
      "first":"John",
      "last":"Doe",
      "full":"John Doe"
    },
    "phone_number":"4151234567",
    "email":"[email protected]"
  },
  order_id: "abc123"
}

If the request is successful, Affirm expects a HTTP 200 response similar to the following:

{
  "currency":"USD",
  "shipping_options":[
    {
      "shipping_id":1,
      "shipping_type":"Standard",
      "shipping_amount":0
    },
    {
      "shipping_id":2,
      "shipping_type":"Express",
      "shipping_amount":1000
    },
    {
      "shipping_id":3,
      "shipping_type":"Overnight",
      "shipping_amount":2000
    }
  ]
  order_id: "abc123"
}

If the request is unsuccessful, Affirm expects a HTTP 422 response similar to the following:

{
  "error_code": "unsupported_shipping_zone",
  "message": "We currently do not offer shipping to Hawaii or Alaska.",
  "fields": ["shipping.address.state"],
}

3. Set up Checkout Total API endpoint

Provide an API endpoint for Checkout Total that:

  • Accepts the cart items and customer shipping details, and
  • Returns the calculated shipping amount, tax amount, and total order amount for the selected shipping method.

We recommend passing the order_id to track checkout sessions in your system. See the Express Checkout API page for complete request and response payload definitions.

On user shipping details confirmation, Affirm sends a request with a payload similar to the following:

{
  // selected shipping option returned from the Shipping Options API Endpoint
  "selected_shipping_option":{
    "shipping_id":1,
    "shipping_type":"Standard",
    "shipping_amount":0
  }  
  // https://docs.affirm.com/developers/reference/the-item-object
  "items":[
    {
      "display_name":"Awesome Pants",
      "sku":"ABC-123",
      "unit_price":1999,
      "qty":3,
      "item_image_url":"http://merchantsite.com/images/awesome-pants.jpg",
      "item_url":"http://merchantsite.com/products/awesome-pants.html",
      "categories":[
        [
          "Apparel",
          "Pants"
        ],
        [
          "Mens",
          "Apparel",
          "Pants"
        ]
      ]
    }
  ],
  // https://docs.affirm.com/developers/reference/shipping-billing-object
  "shipping":{
    "address":{
      "line1":"325 Pacific Ave",
      "city":"San Francisco",
      "state":"CA",
      "zipcode":"94111",
      "country":"US"
    },
    "name":{
      "first":"John",
      "last":"Doe",
      "full":"John Doe"
    },
    "phone_number":"4151234567",
    "email":"[email protected]"
  },
}

If the request is successful, Affirm expects a HTTP 200 response similar to the following:

{
  "currency":"USD",
  "shipping_amount": "1000",
  "shipping_type": "UPS Ground",
  "tax_amount": "800",
  "total": "11800"
}

If the request is unsuccessful, Affirm expects a HTTP 422 response similar to the following:

{
  "error_code": "unsupported_shipping_zone",
  "message": "We currently do not offer shipping to Hawaii or Alaska.",
  "fields": ["shipping.address.state"],
}

4. Retrieve shipping details

If you pass the order_id in step 3 to track the checkout session in your system, this step is optional.

After the user successfully completes an Affirm checkout, you can call Affirm’s Read Checkout API with the checkout ID to retrieve complete shipping information and checkout details:

{
  "total": 20000,
  "selected_shipping_option":{
    "shipping_id":1,
    "shipping_type":"Standard",
    "shipping_amount": 1000 // should match shipping_amount field below
  },
  "shipping_amount": 1000,  
  "shipping": {
    "name": {
      "full": "John Doe",
      "first": "John",
      "last": "Doe"
    },
    "address": {
      "city": "San Francisco",
      "country": "USA",
      "line1": "123 Example Street",
      "line2": "Apt 123",
      "state": "CA",
      "zipcode": "94107"
    },
    "email": "[email protected]",
    "phone_number": "1234567890"
  },
  "billing_frequency": "monthly",
  "currency": "USD",
  "meta": {
    "release": "string",
    "user_timezone": "America/Los_Angeles",
    "_affirm_tracking_uuid": "356a483a-86b2-4846-b6f2-70d37d95a78c"
  },
  "financial_program_external_name": "string",
  "financial_program_name": "standard_3_6_12",
  "checkout_flow_type": "classic",
  "billing": {
    "name": {
      "last": "string",
      "first": "string"
    },
    "phone_number": "1234567890",
    "email": "[email protected]"
  },
  "config": "string",
  "product_type": "string",
  "api_version": "v2",
  "metadata": {
    "checkout_channel_type": "online",
    "mode": "redirect"
  },
  "merchant": {
    "public_api_key": "string",
    "user_cancel_url": "string",
    "user_confirmation_url": "string",
    "user_confirmation_url_action": "string",
    "name": "string",
  },
  "product": "string",
  "order_id": "ABC123",
  "suppress_expiration_declination_messaging": true,
  "mfp_rule_input_data": {
    "items": {
      "sku_number": {
        "sku": 0,
        "item_url": "string",
        "display_name": "string",
        "unit_price": 0,
        "qty": 0,
        "item_type": "string",
        "item_image_url": "string"
      }
    },
    "total": 49999,
    "metadata": {
      "checkout_channel_type": "online",
      "mode": "redirect"
    },
    "financing_program": "string"
  },
  "loan_type": "classic",
  "chekcout_type": "merchant",
  "tax_amount": 0,
  "checkout_status": "string",
    "email": "[email protected]",
    "phone_number": "1234567890"
  },
  "use_adaptive": true,
  "financing_program": "string",
  "merchant_external_reference": "ab-12345"
}

5. Add Affirm Checkout Button

Add the pre-styled Affirm Checkout button on your website for Express Checkout. See Checkout Button for details.

Example:

<div class="affirm-checkout-button-container"
     data-page-type="product"
     data-size="large"
     data-theme="dark"
     data-shape="rounded"
     data-button-text="checkout"
>
</div>

What’s next?

Updated about 3 hours ago