API ReferenceCommerce

Orders

Orders: what a paid checkout becomes, and orders an integration records directly.

Prefix /cdna-api/orders ReferenceOrder model GuideFrom checkout to order

About orders

An order records a sale: its number and uuid, the person, the billing and delivery addresses, the items, the totals, and two statuses, financial (unpaid, authorized, partially_paid, paid, partially_refunded, refunded, voided) and fulfilment (none, pending, partial, fulfilled, completed). A checkout becomes an order once its invoice is paid; an integration can also record orders made elsewhere. There is no delete route.

An order made by a checkout is managed: its items, totals, discounts and statuses follow its invoices and fulfilments, and a write that changes them is refused with “Property cannot be modified in managed orders”. An order created through the API is not managed, and takes them as sent.

Statuses Financial, fulfilment

What has been paid and what has been sent are two statuses, kept apart.

Orders, invoices and fulfilment
Deleting Kept

An order stays once created: it is the record of the sale.

Orders, invoices and fulfilment
Managed From a checkout

A checkout’s order keeps its items, totals and statuses in step with its invoices, which set them.

Orders, invoices and fulfilment
Access Admin users

Members are refused: a 404 by default, a 403 where the site’s access-denied setting says so. Call it from a server with an admin user’s OAuth token or API key.

Authentication and authorisation

Learn more

GuideFrom checkout to order GuideThe checkout and when it can be paid GuidePayment methods and how a payment runs

List orders#

GET /cdna-api/orders/orders

Lists orders. Without limit every match comes back. The order’s metadata fields can be filtered on as well as its own fields. This site has none, as the example shows.

Access
Admin users and integrations, with an OAuth access token or an API key.
Model
Order, in the Reference

Parameters

propertiesquery
selector
The fields and relations to return, such as {id,number,financialStatus,fulfillmentStatus,total}.
filtersquery
name=value
Any stored field, or a relation with a dot, such as parent.id=12. Prefix the name with !, >, <, % or |. Use stored field names exactly as in the model, and compare totalCount with the unfiltered list's to confirm a filter applied.
orderByquery
string
field:ASC or field:DESC, comma-separated. Stored fields only.
limitquery
integer
Records per response. There is no default.
offsetquery
integer
Records to skip.

Example

List orders 
GET /cdna-api/orders/orders?limit=2&properties={id,number,financialStatus,fulfillmentStatus,total} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "totalCount": 0,
  "data": []
}
Real response from this documentation site

Show an order#

GET /cdna-api/orders/order/{id}

Reads one order by its id.

Access
Admin users and integrations, with an OAuth access token or an API key.
Model
Order, in the Reference

Parameters

idpathrequired
integer
The order id.
propertiesquery
selector
The fields and relations to return, such as {id,number,financialStatus,fulfillmentStatus,total}.

Example

Show an order 
GET /cdna-api/orders/order/1 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Create an order#

POST /cdna-api/orders/order

Records an order made outside the checkout, such as a sale in a shop or another system. The uuid is generated, and so is the number when it is left out. The order stays once created.

Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
The new order under data.order, and a message.

Parameters

currencyCodebodyrequired
string
The currency, as a three-letter code such as USD; currency itself cannot be set.
personbodyrequired
integer
The person who ordered, by id.
itemsbodyrequired
list
The lines, at least one: productCode, name, quantity and amount each.
billingAddress, deliveryAddressbody
object
The addresses: firstName, lastName, addressLine1, suburb, stateName, postcode, countryName.
numberbody
string
The order number; generated when left out.
financialStatus, fulfillmentStatusbody
string
The statuses, from the lists above; unpaid and none when left out.

An order stays once created, so try this on a development site.

Example

Create an order 
POST /cdna-api/orders/order HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "currencyCode": "USD",
  "person": 135,
  "billingAddress": {
    "firstName": "Alex",
    "lastName": "Example",
    "addressLine1": "1 Example Street",
    "suburb": "Melbourne",
    "stateName": "VIC",
    "postcode": "3000",
    "countryName": "Australia"
  },
  "items": [
    {
      "productCode": "API-SANDBOX-MUG",
      "name": "API sandbox mug",
      "quantity": 2,
      "amount": "24.00"
    }
  ]
}
Response 422 Unprocessable EntityMissing person and items 
{
  "result": "error",
  "validationErrors": {
    "person": [
      {
        "message": "Person is required.",
        "code": null,
        "propertyPath": "person"
      }
    ],
    "items": [
      {
        "message": "This collection should contain 1 element or more.",
        "code": "bef8e338-6ae5-4caf-b8e2-50e7b0579e69",
        "propertyPath": "items"
      }
    ]
  },
  "message": "A validation error occurred; please check the submitted fields for errors."
}
Real response from this documentation site

Edit an order#

PUT /cdna-api/orders/order/{id}

Changes an order. Fields left out keep their values. On an order made by a checkout, a change to its items, totals, discounts or statuses is refused with “Property cannot be modified in managed orders”.

Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
The saved order under data.order, and a message.

Parameters

idpathrequired
integer
The order id.
number, person, billingAddress, deliveryAddressbody
As for Create an order.
financialStatus, fulfillmentStatus, itemsbody
As for Create an order, on orders created through the API only.

Example

Edit an order 
PUT /cdna-api/orders/order/9 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "fulfillmentStatus": "fulfilled"
}

Calculate a refund#

POST /cdna-api/orders/refund/calculate

Works out a refund on an order without making it: nothing is saved and no status changes. The order’s payment method must support refunds, and the total must be more than 0 and no more than what is left to refund. Invoices has the same calculation by invoice.

Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
The calculated refund under data.refund, with its totals broken out.

Parameters

orderIdbodyrequired
integer
The order id.
refundItemsbody
list
The invoice lines refunded: invoiceItem and quantity.
adjustmentTotalbody
string
Added to the refund; negative for a fee such as restocking.
reasonbody
string
Why.

Example

Calculate a refund 
POST /cdna-api/orders/refund/calculate HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "orderId": 9,
  "refundItems": [
    {
      "invoiceItem": 31,
      "quantity": 1
    }
  ],
  "adjustmentTotal": "-5.00",
  "reason": "Returned, restocking fee"
}
Response 422 Unprocessable EntityUnknown order 
{
  "result": "error",
  "validationErrors": {
    "orderId": [
      {
        "message": "Order does not exist",
        "code": null,
        "propertyPath": "orderId"
      }
    ]
  },
  "message": "A validation error occurred; please check the submitted fields for errors."
}
Real response from this documentation site