API ReferenceCommerce

Checkouts

A checkout made from a cart: the shopper, the addresses, shipping, discount codes, and the purchase that turns it into an order.

Prefix /cdna-api/checkout ReferenceCheckout model GuideThe checkout and when it can be paid

Checkouts in Postman

About checkouts

A checkout is made from a cart’s available items and addressed by its own uuid. It collects the shopper’s email, the billing and delivery addresses, shipping and discount codes; the purchase then takes the payment and, once the invoice is paid, creates the order and deletes the checkout. Any change to the cart deletes its checkout.

The routes need a signed-in user, unless the site allows guest checkout. A signed-in caller’s checkout email must be their own. Saving answers with the warnings that still stand between the checkout and payment, in messages.

Access Shopper or guest

A signed-in user, or anyone when guest checkout is on. Session writes need the CSRF token.

Checkout

Ready to pay Four things

A person with an email, a billing address, and a shipping rate chosen for every fulfilment.

Checkout

Becomes An order

Once paid, it is converted to an order and deleted.

Orders, invoices and fulfilment

Learn more

GuideThe checkout and when it can be paid GuidePayment methods and how a payment runs GuideShipping methods and their templates

Create a checkout#

POST /cdna-api/checkout/{cartUuid}

Makes a checkout from a cart’s available items, or reuses one that covers the same items. The cart is priced again first.

Access: A signed-in member, for their own records, and admin users.
Returns: The new checkout under data.checkout, with its uuid, and a message.

Parameters

cartUuidpathrequired: string; The cart’s uuid.
itemsbody: list; Cart item ids to take; every available item when left out.
person, deliveryAddress, billingAddressbody: object; As for Edit a checkout.

Example

Create a checkout

POST /cdna-api/checkout/f6b4ec7c-8192-43ca-9327-1ba9add89fe3 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{}

Response 200 OK

{
  "result": "success",
  "data": {
    "checkout": {
      "uuid": "6b10835d-a2fe-43d4-80ac-339c7909cc64",
      "person": null,
      "deliveryAddress": null,
      "billingAddress": null,
      "items": [
        {
          "id": 1,
          "productCode": "API-SANDBOX-MUG",
          "name": "API sandbox mug",
          "quantity": 3,
          "discount": "0",
          "tax": "0.0000",
          "amount": "36.0000",
          "available": true
        },
        {
          "id": 2,
          "productCode": "API-SANDBOX-MUG-BLUE",
          "name": "API sandbox mug, blue",
          "quantity": 1,
          "discount": "0",
          "tax": "0.0000",
          "amount": "14.0000",
          "available": true
        }
      ],
      "metadataFieldValues": [],
      "fulfillments": [],
      "currency": {
        "id": 142,
        "shortName": "USD",
        "symbol": "$",
        "symbolLocation": "left",
        "decimalPlaces": 2
      },
      "discountCodes": [],
      "discountTotal": "0",
      "surchargeTotal": "0",
      "shippingTotal": "0",
      "handlingTotal": "0",
      "insuranceTotal": "0"
    }
  },
  "message": "The Checkout has been added successfully."
}

Open in Postman docs Real response from this documentation site, shortened

Show a checkout#

GET /cdna-api/checkout/{uuid}

Reads a checkout, with messages listing what still blocks payment.

Access: A signed-in member, for their own records, and admin users.
Model: Checkout, in the Reference

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
propertiesquery: selector; The fields to return, under the checkout key.

Example

Show a checkout

GET /cdna-api/checkout/6b10835d-a2fe-43d4-80ac-339c7909cc64?properties={checkout{uuid,total,items{productCode,quantity,amount},fulfillments{shippingRates,selectedShippingRate}}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "checkout": {
      "uuid": "6b10835d-a2fe-43d4-80ac-339c7909cc64",
      "total": "44.0000",
      "items": [
        {
          "productCode": "API-SANDBOX-MUG",
          "quantity": 3,
          "amount": "30.0000"
        },
        {
          "productCode": "API-SANDBOX-MUG-BLUE",
          "quantity": 1,
          "amount": "14.0000"
        }
      ],
      "fulfillments": [
        {
          "shippingRates": [],
          "selectedShippingRate": null
        }
      ]
    }
  },
  "messages": [
    {
      "type": "warning",
      "message": "Checkout has no person",
      "deleteUrl": null
    },
    {
      "type": "warning",
      "message": "A fulfillment has no shipping rate selected",
      "deleteUrl": null
    }
  ]
}

Open in Postman docs Real response from this documentation site

Edit a checkout#

PUT /cdna-api/checkout/{uuid}

Sets the shopper’s email, the addresses and the order metadata, the only fields it accepts. The answer lists in messages what still blocks payment.

Access: A signed-in member, for their own records, and admin users.
Returns: The checkout under data.checkout, a message, and messages with the warnings still standing.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
personbody: object; {"email": …}: a guest’s email, or for a signed-in caller their own.
billingAddress, deliveryAddressbody: object; firstName, lastName, addressLine1, addressLine2, suburb, stateName, postcode, countryName.
metadataFieldValuesbody: list; Answers to the order’s metadata fields.

Example

Edit a checkout

PUT /cdna-api/checkout/6b10835d-a2fe-43d4-80ac-339c7909cc64?properties={checkout{uuid,person{email},billingAddress{firstName,lastName,addressLine1,postcode,countryName},total}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "billingAddress": {
    "firstName": "Alex",
    "lastName": "Example",
    "addressLine1": "1 Example Street",
    "suburb": "Melbourne",
    "stateName": "VIC",
    "postcode": "3000",
    "countryName": "Australia"
  }
}

Response

{
  "result": "success",
  "data": {
    "checkout": {
      "uuid": "6b10835d-a2fe-43d4-80ac-339c7909cc64",
      "person": null,
      "billingAddress": {
        "firstName": "Alex",
        "lastName": "Example",
        "addressLine1": "1 Example Street",
        "postcode": "3000",
        "countryName": "Australia"
      },
      "total": "50.0000"
    }
  },
  "message": "The Checkout has been saved successfully.",
  "messages": [
    {
      "type": "warning",
      "message": "Checkout has no person",
      "deleteUrl": null
    },
    {
      "type": "warning",
      "message": "A fulfillment has no shipping rate selected",
      "deleteUrl": null
    }
  ]
}

{
  "result": "error",
  "validationErrors": {
    "person.email": [
      {
        "message": "The checkout email must match your profile email.",
        "code": null,
        "propertyPath": "person.email"
      }
    ]
  },
  "message": "A validation error occurred; please check the submitted fields for errors."
}

Open in Postman docs Real response from this documentation site

Add delivery or pickup#

POST /cdna-api/checkout/{uuid}/shipping/{algorithm}

Replaces the checkout’s fulfilments with new ones made by the shipping method in the path, and lists their rates. This site has no shipping rates set up, so shippingRates is empty here.

Access: A signed-in member, for their own records, and admin users.
Returns: The checkout under data.checkout, its fulfilments with their shippingRates, and the message “Shipping created”.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
algorithmpathrequired: string; simple-delivery or simple-pickup.
firstName, lastName, addressLine1, addressLine2, suburb, stateName, postcode, countryNamebody: string; The delivery address; countryName, addressLine1 and postcode are required.

Example

Add delivery or pickup

POST /cdna-api/checkout/6b10835d-a2fe-43d4-80ac-339c7909cc64/shipping/simple-delivery HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "firstName": "Alex",
  "lastName": "Example",
  "addressLine1": "1 Example Street",
  "suburb": "Melbourne",
  "stateName": "VIC",
  "postcode": "3000",
  "countryName": "Australia"
}

Response 200 OK

{
  "result": "success",
  "data": {
    "checkout": {
      "uuid": "6b10835d-a2fe-43d4-80ac-339c7909cc64",
      "person": null,
      "deliveryAddress": null,
      "billingAddress": null,
      "items": [
        {
          "id": 1,
          "productCode": "API-SANDBOX-MUG",
          "name": "API sandbox mug",
          "quantity": 3,
          "discount": "0.0000",
          "tax": "0.0000",
          "amount": "36.0000",
          "available": true
        },
        {
          "id": 2,
          "productCode": "API-SANDBOX-MUG-BLUE",
          "name": "API sandbox mug, blue",
          "quantity": 1,
          "discount": "0.0000",
          "tax": "0.0000",
          "amount": "14.0000",
          "available": true
        }
      ],
      "metadataFieldValues": [],
      "fulfillments": [
        {
          "deliveryAddress": {
            "companyName": null,
            "firstName": "Alex",
            "lastName": "Example",
            "addressLine1": "1 Example Street",
            "addressLine2": null,
            "suburb": "Melbourne",
            "city": null,
            "stateName": "VIC",
            "postcode": "3000",
            "countryName": "Australia",
            "phone": null
          },
          "warehouse": null,
          "shippingRates": [],
          "selectedShippingRate": null,
          "fulfillmentItems": [
            {
              "id": 1,
              "item": 1,
              "quantity": 3,
              "discount": "0.0000",
              "tax": "0.0000",
              "amount": "36.0000"
            },
            {
              "id": 2,
              "item": 2,
              "quantity": 1,
              "discount": "0.0000",
              "tax": "0.0000",
              "amount": "14.0000"
            }
          ]
        }
      ],
      "currency": {
        "id": 142,
        "shortName": "USD",
        "symbol": "$",
        "symbolLocation": "left",
        "decimalPlaces": 2
      },
      "discountCodes": [],
      "discountTotal": "0.0000",
      "surchargeTotal": "0.0000",
      "shippingTotal": "0.00",
      "handlingTotal": "0.0000",
      "insuranceTotal": "0.0000"
    }
  },
  "message": "Shipping created"
}

Real response from this documentation site, shortened

Choose a shipping rate#

PUT /cdna-api/checkout/{uuid}/shipping/{id}

Chooses one of a fulfilment’s rates and prices the checkout again. There is no body.

Access: A signed-in member, for their own records, and admin users.
Returns: The checkout under data.checkout.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
idpathrequired: integer; The shipping rate’s id, from the fulfilment’s shippingRates.

Example

Choose a shipping rate

PUT /cdna-api/checkout/9a1c7e3b-2d4f-4b6a-8c5e-1f0d2b7a6e43/shipping/12 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Apply a discount code#

POST /cdna-api/checkout/{uuid}/discount-code

Applies a discount code. Unlike the cart, an unknown code is an HTTP error, 400.

Access: A signed-in member, for their own records, and admin users.
Returns: The checkout under data.checkout.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
codebodyrequired: string; The discount code.

Example

Apply a discount code

POST /cdna-api/checkout/6b10835d-a2fe-43d4-80ac-339c7909cc64/discount-code HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "code": "SAVE10"
}

Response 400 Bad Request

{
  "result": "error",
  "message": "Discount code does not exist"
}

Open in Postman docs Real response from this documentation site

Remove discount codes#

DELETE /cdna-api/checkout/{uuid}/discount-code/{code}

Removes the code in the path, or every code when the path ends at discount-code, as here.

Access: A signed-in member, for their own records, and admin users.
Returns: The checkout under data.checkout, and a message.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
codepath: string; The code; left out, all of them.

Example

Remove discount codes

DELETE /cdna-api/checkout/6b10835d-a2fe-43d4-80ac-339c7909cc64/discount-code?properties={checkout{uuid,discountCodes,discountTotal,total}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "checkout": {
      "uuid": "6b10835d-a2fe-43d4-80ac-339c7909cc64",
      "discountCodes": [],
      "discountTotal": "0",
      "total": "44.0000"
    }
  },
  "message": "Discount code was removed from checkout"
}

Open in Postman docs Real response from this documentation site

Purchase#

POST /cdna-api/checkout/{uuid}/purchase

Takes the payment with the chosen payment method. Act on data.code and data.action: paid (the order exists), pending (send the shopper to payment processing), or authentication required (complete 3-D Secure in the browser).

Access: A signed-in member, for their own records, and admin users.
Returns: data.state, data.code and data.action; when paid, data.order.uuid. A declined card is a 500 with the provider’s message.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.
_paymentMethodIdbodyrequired: integer; An active payment method’s id, from Invoices.
_recaptchaTokenbody: string; The reCAPTCHA token, when the site uses one. Without it the answer is 500 “Recaptcha validation failed”.
(the provider’s fields)body: Passed to the payment provider, such as confirmationToken for Stripe or paypalOrderId for PayPal.

A purchase creates records that stay: a paid invoice cannot be deleted and an order never can. Test on a development site, with the Mock Pay method, which moves no money.

Example

Purchase

POST /cdna-api/checkout/9a1c7e3b-2d4f-4b6a-8c5e-1f0d2b7a6e43/purchase HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "_paymentMethodId": 1,
  "_recaptchaToken": "TOKEN_FROM_RECAPTCHA"
}

Response

{
  "result": "success",
  "data": {
    "state": "success",
    "action": {
      "type": "redirect",
      "method": "GET",
      "url": "https://www.example.com/checkout/complete/bde48fcb-e194-4007-bc51-b78a25e4dd55"
    },
    "code": "PAYMENT_SUCCESSFUL",
    "order": {
      "uuid": "bde48fcb-e194-4007-bc51-b78a25e4dd55"
    }
  },
  "message": "Payment successful"
}

{
  "result": "success",
  "data": {
    "state": "pending",
    "action": {
      "type": "redirect",
      "method": "GET",
      "url": "/checkout/payment-processing"
    },
    "code": "PAYMENT_PENDING"
  },
  "message": "Redirect to payment processing"
}

{
  "result": "success",
  "data": {
    "state": "pending",
    "action": {
      "type": "authenticate",
      "data": {
        "paymentIntentId": "pi_EXAMPLE",
        "clientSecret": "pi_EXAMPLE_secret_EXAMPLE"
      }
    },
    "code": "PAYMENT_AUTHENTICATION_REQUIRED"
  },
  "message": "Authentication required"
}

{
  "result": "error",
  "message": "Checkout is not ready for payment",
  "messages": [
    {
      "type": "warning",
      "message": "Checkout has no person",
      "deleteUrl": null
    },
    {
      "type": "warning",
      "message": "Billing address has not been set",
      "deleteUrl": null
    }
  ]
}

Open in Postman docs Saved responses from the Postman collection; the 400 from the platform’s source

Learn more

GuidePayment methods and how a payment runs

Poll a payment#

GET /cdna-api/checkout/{uuid}/payment-processing

For a payment that is still being confirmed: answers 202 with "shouldPoll": true while it is pending, and "status": "completed" with the redirectUrl to send the shopper to once it is decided. It answers outside the API’s envelope.

Access: Anyone. The route takes no credentials, by design.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.

Example

Poll a payment

GET /cdna-api/checkout/6b10835d-a2fe-43d4-80ac-339c7909cc64/payment-processing HTTP/1.1
Host: hub.coredna.com
Accept: application/json

Response 200 OK

{
  "status": "completed",
  "redirectUrl": "/checkout",
  "shouldPoll": false
}

Real response from this documentation site

Delete a checkout#

DELETE /cdna-api/checkout/{uuid}

Deletes a checkout. The cart stays, so the shopper can start again.

Access: A signed-in member, for their own records, and admin users.
Returns: The deleted checkout under data.checkout.

Parameters

uuidpathrequired: string; The checkout’s uuid, from Create a checkout.

Example

Delete a checkout

DELETE /cdna-api/checkout/9a1c7e3b-2d4f-4b6a-8c5e-1f0d2b7a6e43 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Open in Postman docs

Objects ReferenceGenerated from the platform, so it is always current

API ReferenceEvery REST endpoint, in cURL, PHP, Python and JavaScript

Checkouts

About checkouts

Learn more

Create a checkout#

Parameters

Example

Show a checkout#

Parameters

Example

Edit a checkout#

Parameters

Example

Add delivery or pickup#

Parameters

Example

Choose a shipping rate#

Parameters

Example

Apply a discount code#

Parameters

Example

Remove discount codes#

Parameters

Example

Purchase#

Parameters

Example

Learn more

Poll a payment#

Parameters

Example

Delete a checkout#

Parameters

Example