Skip to main content

Creating Orders

The Partner API takes bank transfer payments only. Whenever you create a bulk order, an assignment order or a kit order through the API, we send the invoice to your registered partner billing email automatically.

Ordering Flows​

There are two ordering flows to choose from.

Standard orders (also called bulk orders) are what most partners use. You pay for the kits and the assignments together, upfront, and get back tokens you can spend on assignment orders later at no extra cost.

Why most people pick this:

  • One payment covers everything
  • You get assignment tokens to use whenever you need them
  • Creating an assignment later costs you nothing
  • Easier to budget and plan for

How it works:

  1. Create a standard order specifying the number of kits needed
  2. Pay via bank transfer (invoice sent automatically)
  3. Receive assignment tokens equivalent to the number of kits ordered
  4. Use tokens when creating assignment orders (no additional charges)

Example workflow:

POST /orders
{
  "numberOfKits": 50,
  "paymentType": "bank-transfer"
}

That gets you 50 assignment tokens to spend on future assignments, at no extra cost.

2. Kit Orders (Alternative Flow)​

With kit orders you buy the physical kits on their own and pay for assignments separately, as you need them.

How it works:

  1. Order kits through the kit endpoint
  2. Pay for the kits by bank transfer (invoice sent automatically)
  3. Later, create assignment orders and pay for each one separately

Worth considering if:

  • You need kits on hand now but won't assign them for a while
  • You order in smaller batches, more often
  • You'd rather pay for assignments as they come up

Example workflow:

POST /kits
{
  "numberOfKits": 10
}

Then later, when creating assignments:

POST /assignments
{
  "sets": [...],
  "paymentType": "bank-transfer"
}

Each assignment gets its own invoice.

Shipping directly to a patient​

Both flows above ship to your practice's address. To send a kit straight to a patient's home instead, place a direct-to-patient kit order. You can ship to as many different patients as you like from one practice; the address lives on each patient, not on the practice.

How it works:

  1. Save the patient's delivery address on their patient record. address, city, country and zip are required to ship; state and phone are optional.
  2. Place a kit order with the patient's ID.
  3. We ship the kit to the patient and assign it to them when it ships, so there's no separate assignment step. You're invoiced once, for the kit and the report together.

Example workflow:

Create the patient with their address (or add it to an existing patient with PUT /patients/{id}):

POST /patients
{
  "name": "Jane Doe",
  "dateOfBirth": "1980-04-12",
  "gender": "F",
  "ethnicity": "...",
  "address": "12 High Street",
  "city": "London",
  "country": "GB",
  "zip": "SW1A 1AA",
  "phone": "+44 20 7946 0000"
}

Then order a kit for them:

POST /kits
{
  "patientId": "..."
}

The response is a normal kit order with patientId set. A direct-to-patient order is always one kit. The kit ships to the address on the patient record when you place the order, so update the patient first if the address changes. If the patient's address is incomplete, the order is refused with a 400 that names the missing fields.

Self-fulfilled orders​

Some accounts fulfil their own orders from kit stock they already hold. If yours is one of them, an order is fulfilled the moment you create it. There's no warehouse step and nothing to wait for, and the kit codes come straight back in the create response.

POST /orders
{
  "numberOfKits": 2
}
{
  "id": "...",
  "numberOfKits": 2,
  "status": "pending",
  "approved": true,
  "kits": ["GA-AF-A00000", "GA-AF-A00001"],
  "units": [
    { "kitCode": "GA-AF-A00000", "externalId": null },
    { "kitCode": "GA-AF-A00001", "externalId": null }
  ]
}

status still tracks payment rather than fulfilment, so it stays pending until the invoice is settled. The partner_order.shipped webhook fires as usual, with trackingCode and trackingLink set to null, so anything you've built around the webhook keeps working unchanged.

Not sure whether your account is set up this way? If kits comes back in the create response, it is. Otherwise, ask your account manager.

Payment and Invoicing​

  • Payment method: bank transfer only
  • Invoicing: we send invoices to your registered billing email automatically, whatever the order type
  • Approval: kit orders need to be approved by our team first
  • What you get billed for:
    • Bulk orders: one invoice covering kits and assignments
    • Kit orders: one invoice for the kits, plus one for each assignment batch
    • Direct-to-patient orders: one invoice covering the kit and the report

Getting Started​

  1. Set your billing email in your partner profile
  2. Generate API keys from your partner dashboard
  3. Pick whichever ordering flow suits how you work
  4. If you're not sure, start with bulk orders. They're the simplest to run.
Test in the sandbox first

Try these flows end to end in the sandbox before you go live. Orders, assignments and the lab lifecycle are all simulated there, so you won't be invoiced and no real kits will ship while you're still building.

For endpoint-by-endpoint detail and more examples, see the full API documentation.