Discover, preview, execute.

00Read this first

Partner checkout builds on the platform-wide API admin and OAuth flows. It is written for external developers who cannot inspect the source code. Read these guides before implementing checkout:

Those guides explain how to obtain access tokens, configure scopes, and authenticate as an API admin reseller.

01What partner checkout does

Partner checkout lets an eligible reseller create and manage a billed-account signup on behalf of a new client. The API can:

• discover which products and add-ons are currently valid for the reseller
• list allowed billing countries and zone codes
• check whether an email, ABN, or NZ employer IRD number is already in use
• preview pricing and validation results before creating anything
• create the customer, address, company record, order, subscription, add-ons, totals, and post-pay record
• optionally send the client a welcome email with a password-reset link
• replay a previously successful execute request safely by idempotency key
• list, inspect, and cancel orders created by that reseller
• end a client's paid subscription early, after previewing exactly what would end
• start a client on a free trial with no order and nothing to pay, then convert that trial into a paid subscription later (see "Free Trials")

02Base URL and authentication

• Base path: /api
• Auth header: Authorization: Bearer <access_token>
• Caller must be an API admin reseller in customer group 9

If the authenticated customer is not an API admin, or is not in group 9, the API returns 403.

03OAuth scopes

openid is still required on the OAuth authorization request. Legacy openapi remains accepted in the wider OAuth flow.

04Recommended integration sequence

To let the client evaluate the product before paying, start at "Free Trials" below instead of step 4, then come back to steps 4 and 5 with end_customer_id when the trial ends.

05Country, identifier & address rules

Only Australia (AU) and New Zealand (NZ) are supported. Country is inferred from the company identifier:

• You must provide exactly one of abn or ird_number.
• billing_address.country_code is not accepted in requests.
• billing_address.company is not accepted in requests.
• customer.password is not accepted in requests.
• billing_address.zone_code must match the inferred country.
• zone_code is case-insensitive in the request and normalized to uppercase.
• If a zone is invalid, the API returns 422 and includes the valid codes for that country in the error detail.

06Endpoint reference

1. Discover products and pricing

Use this endpoint to discover the current subscription products, add-on products, pricing, required scopes, and reseller-specific mandatory requirements.

Important response areas:

• subscription_products: valid base products for order.product_id
• add_on_products: optional or required add-ons
• mandatory_requirements.training_session_product_id: the optional training session product you can add via order.include_training_session
• mandatory_requirements.training_session_product_name / mandatory_requirements.training_session_prices: display name and per-country (AU/NZ) retail pricing for the optional training session line, so the setup fee can be shown before previewing an order. These match the one-off training_session line returned by preview/execute when requested (full retail price, no partner discount, RRP equal to its own price)
• mandatory_requirements.required_owned_add_on_keys: branded add-on families this reseller must include for new client signups
• per_employee_minimum: minimum quantity for per-employee base products
• show_per_employee_pricing: whether this reseller can use per-employee plans
• prices: country-specific partner pricing and, where available, retail RRP comparison values

2. Discover zones

Use this endpoint to fetch the supported countries and valid zone_code values for billing addresses. The response currently includes AU and NZ. Use the returned zone.code values as billing_address.zone_code.

3. Check availability

Use this endpoint to check whether one or more proposed identifiers are already in use.

Query parameters: email, abn, irdNumber. You can send any combination of these in one request, but at least one must be provided.

Each result includes provided, normalized, valid_format, exists, available, message, required_owned_add_ons, has_all_required_owned_add_ons.

Normalization behaviour: emails are trimmed and lowercased; ABNs and IRD numbers are digit-normalized before validation.

The response also always includes a coarse claim object. Only a valid email plus exactly one valid country identifier can return eligible or ineligible; partial or invalid checks return incomplete. Stable status/message pairs are not_applicable/no_existing_customer, incomplete/claim_check_incomplete, eligible/existing_trial_claimable, and ineligible/existing_customer_not_claimable. This check is guidance only: it takes no lock or reservation, and never returns a matched customer ID.

4. Preview or execute an order

Use this endpoint to preview validation and pricing with dry_run=true, or to create the full customer and order with dry_run=false.

Headers: Authorization: Bearer <token>, Content-Type: application/json, Idempotency-Key: <unique value> required for dry_run=false.

Request body

Business rules

• Duplicate customer email, ABN, and IRD values block checkout, unless they belong to the client named by end_customer_id or checkout safely claims an eligible self-service trial. Send claim_existing_trial=false to opt out of that automatic claim.
• Unknown fields are rejected with 422.
• Base product_id must be a subscription product, not an add-on.
• Per-employee products are only allowed when the reseller is configured for them.
• Non-per-employee products reject per_employee_qty.
• Per-employee products reject extra_company_qty.
• extra_company_qty may be capped to the plan limit; when capped, a warning is returned.
• Extra-company add-ons must not be passed directly in add_on_product_ids; use extra_company_qty.
• Every chosen add-on must match the base product's billing cycle.
• If the reseller owns required branded add-on integrations, the corresponding partner add-on products must be included.
• The training session product is optional. Set order.include_training_session: true to add it; omit it or leave it false to skip it. When requested, the product must be configured and active or the request 400s.
• When subscription_end_date is supplied, the base subscription and recurring add-ons are prorated; a requested training session line is still charged at full price. See "Subscription term alignment & prorating".

Preview response

When dry_run=true, nothing is created. The response still contains the fully resolved pricing and address information:

• mode = "preview"
• validated = true
• customer_id, address_id, order_id, and subscription_id are null
• order_lines shows the base subscription, the training session line when requested via include_training_session, and any add-ons
• totals shows subtotal, tax, total, and any welcome-offer promo discount
• warnings describes non-fatal conditions such as capped extra-company quantity or the free trial month
• free_trial_month_applied says whether a free month was granted on this order
• claimed_existing_trial remains false in preview because no claim has committed

Execute response

When dry_run=false, the API creates the normal billed-account order, totals, products, subscription, post_pay, history, and optional add-ons/promo. It creates a customer and company for a new signup, or safely reuses the existing customer/company for an authorised conversion or claim.

Important execute response fields: customer_id, address_id, order_id, subscription_id, order_status_id, claimed_existing_trial, emails_sent, idempotency_replayed.

OAuth single-flow onboarding (oauth_onboarding)

Normally, provisioning a customer and getting an OAuth payroll.write token for them are two separate loops: you create the order, the customer sets a password from the welcome email, then they (or you) run the OAuth ceremony separately before you can create their payroll company.

Supplying an oauth_onboarding block collapses that into a single flow:

No second login and no separate OAuth round-trip are required. After consent the customer is given the chance to set a password (or skip and do it later) before landing back on your callback.

Requirements and behaviour:

• You must have a registered OAuth client on your account (a 1-to-1 client owned by your api-admin customer). The redirect_uri must exactly match one of its registered redirect URIs, and scope must include payroll.write. A dry_run=true request validates all of this without creating anything or sending email.
• The magic link is emailed only to the customer's verified address and is never returned in the API response. Handing a partner a passwordless login link would bypass the consent this flow exists to capture.
• The link is single-use and expires after 7 days. Re-provisioning (a new order) issues a fresh link.
• oauth_onboarding replaces the password-reset welcome email; send_customer_welcome_email is ignored when it is supplied.

See also the OAuth Authentication Guide for the token exchange this flow feeds into.

5. Cancel an order

Use this endpoint to cancel an order previously created by the authenticated reseller, including an upgrade order. Cancelling voids the charge (order_status_id becomes 7) and removes the add-ons sold on the order.

{
  "order_id": 192484,
  "reason": "Client signed up in error.",
  "end_subscription": true
}

• Reseller must own the order.
• Order must not already be cancelled.
• Cancellation is only allowed within 60 days of the order's date_added.
• partner.checkout.cancel is preferred, but partner.checkout.write is also accepted.
• Access. On its own a cancel does not end the client's access: the order's subscription keeps working until its expiry date, and it does not renew. Send end_subscription: true to end that access now as well (its expiry is set to yesterday). Any subscription it replaced whose access is still running is ended with it, the same set POST /api/partner-checkout/subscriptions/end ends. Each subscription ended is listed in ended_subscription_ids. end_subscription defaults to false, so existing integrations behave as before. To end access after the 60-day window, or without voiding the charge, use POST /api/partner-checkout/subscriptions/end.
• When end_subscription: true is refused. The cancel returns 409 and changes nothing when a subscription on the order has since been renewed or upgraded into one that still runs (the client's access is on that one, which this cancel cannot end: cancel without end_subscription and end the subscription the message names with /subscriptions/end), or when a subscription it would end carries add-ons sold on another order that is still billed (cancel the order the message names first, or cancel without end_subscription and end the subscription separately).
• Renewals. Either way, a pending renewal order of the order's subscriptions is cancelled, because a subscription sold on a cancelled order never renews. Each is listed in voided_renewal_order_ids.
• Add-on upgrade orders. Cancelling one removes only the add-ons it sold. The subscription they were added to is unchanged, even with end_subscription: true. If that subscription was later upgraded with credit, which counted those add-ons' remaining value, the cancel returns 409: cancel the later upgrade order first, with end_subscription: true. The check is cautious: any credit on that upgrade blocks the cancel, even when the credit did not cover these particular add-ons.
• Base or both-mode upgrade orders. Cancelling one must reverse the upgrade, so it requires end_subscription: true and returns 409 without it. The upgrade's new subscription is ended, and the subscription it replaced becomes current again with its own expiry. That subscription is listed in restored_subscription_ids, and its own order gets a history note; check its renewal_state to see whether it will renew. A replaced subscription whose own expiry has already passed is made current again but grants no access, so it is not listed.
• An order whose subscription was later upgraded with credit returns 409: the upgrade counted the subscription's remaining value as paid. Cancel the upgrade order first, with end_subscription: true, then this one. A subscription that was only renewed does not block a cancel without end_subscription.
• An upgrade whose new subscription has since been renewed or upgraded again returns 409; contact support to reverse it.
• No Idempotency-Key is needed: cancelling twice returns 409.

{
  "order_id": 192484,
  "previous_order_status_id": 5,
  "order_status_id": 7,
  "order_history_id": 5512,
  "comment": "Order cancelled by partner api admin (customer_id=10452). Reason: Client signed up in error. Ended subscription(s) 98321 (expiry was 2027-09-30) as of 2026-10-05, so access has ended.",
  "ended_subscription_ids": [98321],
  "restored_subscription_ids": [],
  "voided_renewal_order_ids": []
}

{
  "detail": "Order 192530 added add-ons to subscription 98321, which was upgraded into 98455 on order 192611, and that upgrade credited the add-ons' remaining value, so this order can no longer be cancelled. Cancel order 192611 with end_subscription=true first."
}

6. Inspect one order

Returns the current status and history for one order created by the reseller, including totals and currency, customer and company details, subscription ID and expiry, cancel_window_closes, cancellable, and ascending history[].

cancellable means the order is not already cancelled and is still inside its 60-day window. A cancel can still return 409 for an upgrade order, or for an order whose subscription was later upgraded with credit; see "Cancel an order" above.

7. List orders

Lists only the orders created by the authenticated reseller, newest first. Query parameters: status, limit, offset.

8. Recover onboarding or OAuth connection

Emails the safe recovery path for the customer created by one of your orders. An unestablished customer receives a fresh single-use magic onboarding link. An established customer whose OAuth connection is missing receives a normal sign-in and authorization link instead.

Request body mirrors the oauth_onboarding block of POST /api/partner-checkout/orders:

{
  "oauth_onboarding": {
    "redirect_uri": "https://partner.example.com/oauth/callback",
    "scope": "openid payroll.write",
    "state": "partner-corr-abc123"
  }
}

The original redirect_uri/scope/state are never stored, so you must supply them again. They are re-validated against your current OAuth client, so a deleted client or a changed redirect URI fails 400 rather than minting a dead link.

Rules:

• Requires partner.checkout.write.
• Reseller must own the order.
• The customer must have been provisioned with oauth_onboarding originally by your account.
• A customer who opened the link but never finished the consent flow can be sent a fresh one. The link is single-use, so it is spent by that first click even though onboarding never completed.
• An established customer is never sent a new passwordless link. They receive a normal OAuth authorization URL and must sign in before consenting.
• A customer who already has a live OAuth connection to your client returns 409; no email is sent.
• Any previously issued, unused link is invalidated; only the newest link works.
• The magic link is emailed only to the customer's verified address and is never returned in the response.
• If the email cannot be sent, the call returns 502 and no new link is issued.

{
  "customer_id": 192601,
  "order_id": 192484,
  "email_sent": true,
  "recovery_action": "magic_onboarding",
  "expires_in_hours": 168,
  "scope_used": "partner.checkout.write"
}

For an established but disconnected customer, recovery_action is oauth_reauthorization and expires_in_hours is null.

07Free trials

A free trial lets your client evaluate Lightning Payroll before anyone is billed. It is deliberately not an order:

• No order, order line, order total, or post-pay record is created.
• Nothing appears on an invoice, and you are not billed.
• The trial subscription is never renewed.
• The trial runs for one calendar month from the day you create it.

When the trial ends, you place the real order with POST /api/partner-checkout/orders and pass the trial's customer_id as end_customer_id.

Trial sequence

The free month is once per client

order.add_free_trial_month defaults to true and adds one extra month to the subscription, so a monthly signup gets 2 months and an annual signup gets 13.

That free month is granted once per client. If the client has already had a free trial, whether from POST /api/partner-checkout/trials, a signup on our website, or an earlier order of yours that carried a free month, it is not granted a second time.

When that happens the request still succeeds. It does not error:

{
  "free_trial_month_applied": false,
  "warnings": [
    "A free trial month was already provided for this customer, so no additional free month was applied to this order."
  ]
}

Ordering for an existing client

Send end_customer_id on POST /api/partner-checkout/orders to order for a client you already provisioned. Then:

• No new customer record is created; the order attaches to that client.
• The customer block is still required, and customer.email must match that client's email, otherwise the API returns 409. This stops an order being attached to the wrong account.
• The company block is still required. Re-sending the same ABN or IRD number is accepted because that client already holds it.
• The client's billing address is updated in place from billing_address.
• Any still-running trial subscription is retired, so the paid plan's employee and company limits take effect immediately.
• A subscription still running on an order that was cancelled (or is otherwise not complete) is retired the same way: its access ends yesterday and any pending renewal order for it is cancelled. Nobody is paying for it, and leaving it running would keep its limits beside the new plan's. The dry run lists each one in warnings, and the order's history records how many were retired.
• The new subscription starts today and runs a full term.
• The password-reset welcome email is not resent, since the client already has a password. Use POST /api/partner-checkout/orders/{order_id}/resend-onboarding-link when their onboarding or OAuth connection needs recovery.

You may only pass an end_customer_id for a client you provisioned, meaning a trial you created or a client you already have an order for. Anything else returns 403. An unknown ID returns 404.

A client who still has a live paid subscription cannot be ordered for again: a second order would add a second, overlapping subscription that renews alongside the first. The dry run and the execute both return 409, and nothing is written. For a subscription you sold, the message names it and the endpoint to use instead:

{
  "detail": "Customer 192601 already has an active paid subscription 88412 (expires 2027-03-31). Ordering again would add a second, overlapping subscription. To change their plan now use POST /api/partner-checkout/upgrades with subscription_id 88412; to change what they renew onto use PATCH /api/partner-checkout/renewals/88412; to stop it first use POST /api/partner-checkout/subscriptions/end."
}

• To move the client to a different plan now, with credit for the unused time, use POST /api/partner-checkout/upgrades.
• To change the plan they move onto at renewal, use PATCH /api/partner-checkout/renewals/{subscription_id}.
• To stop the subscription and then order afresh, end it with POST /api/partner-checkout/subscriptions/end (no refund or credit), then place the order.
• On the subscription's expiry day it can no longer be upgraded, and the 409 says so: order again from the next day, once it has ended, or end it first.
• If the live paid subscription was not sold through your account (the client bought directly, or through another reseller), the 409 says so without naming it. Contact Lightning Payroll support before ordering for that client.
• A subscription still running on an order you placed and later cancelled is retired by the new order (its access ends yesterday and any pending renewal order is cancelled), and the dry run lists it in warnings. One running on an order someone else placed returns 409 pointing to Lightning Payroll support.

A client whose paid subscription has lapsed, was ended early, or was sold on an order that is now cancelled can be ordered for again. A retry of an order that already succeeded, with the same Idempotency-Key and payload, still replays the original response.

Claiming an existing self-service trial

If checkout finds that the email already belongs to a customer who signed up for a self-service trial, it automatically attempts to reuse that account instead of creating a duplicate or requiring a partner software change.

1. Continue sending the existing new-customer order payload without end_customer_id. Omitted claim_existing_trial automatically requests the safe claim.
2. Optionally call GET /api/partner-checkout/availability with the email and exactly one valid country identifier: abn or irdNumber, for non-authoritative guidance before preview or execute.
3. Preview, then execute the same payload with a new Idempotency-Key. Send claim_existing_trial=true only when you want to state the request explicitly.
4. Persist the response and check claimed_existing_trial=true. Send claim_existing_trial=false only when you deliberately require the previous duplicate-email 409.

The authenticated API-admin partner and its checkout-write scope are sufficient authority for this limited commercial claim. No customer data access or OAuth consent transfers with it. claim_existing_trial=true explicitly requests the same claim; false opts out. With end_customer_id, the existing authorised conversion remains unchanged. If the email has no existing customer, the request follows normal new-customer creation and returns claimed_existing_trial=false.

The server rechecks eligibility under database locks during execute. A claim is allowed only for one normal, active self-service-trial customer with no order history, paid/renewing subscription, partner-attributed trial, conflicting live onboarding/OAuth relationship, API branding/client ownership, or identifier owned by another customer. Availability is not a reservation, so execute can still return 409 if the account changes first. The response deliberately does not reveal which internal check failed.

• The existing customer ID, login, password, profile, users, payroll data, cards, and integrations remain intact. Only the submitted billing address is refreshed.
• A normal paid partner order and subscription are created, and still-running trial entitlements are retired.
• The customer's ABN/IRD record is reused only when it is unclaimed or already belongs to that same customer; it is never transferred from another customer.
• The customer receives a mandatory informational notice naming your account and the claim reference. It says their account is intact, the claim did not grant payroll access, and OAuth still needs separate consent. send_customer_welcome_email=false does not suppress this notice.
• Your account must have an actionable branding-compatible support contact before claiming. If a sending domain is configured, it must be verified first; the required notice never silently falls back to a Lightning Payroll sender for that domain.
• Cancelling the resulting order follows the normal 60-day order policy. It does not delete the customer, erase the relationship audit, or automatically “unclaim” the account.

9. Create a trial

Creates a client on a free one-month trial. Requires partner.checkout.write and an Idempotency-Key.

{
  "customer": {
    "first_name": "Alice",
    "last_name": "Nguyen",
    "email": "alice@example.com",
    "phone": "+61 7 3000 0000"
  },
  "company": {
    "legal_name": "Sunrise Hospitality Pty Ltd",
    "abn": "10000000000"
  }
}

Rules:

• The company's ABN or IRD number is claimed at this point, so no other reseller can start a competing trial for the same entity, and your later order for that company is accepted.
• A duplicate client email returns 409.
• An ABN or IRD number already held by a different client returns 409.
• Too many claim attempts in a minute returns 429.
• The client's onboarding email carries your branding when you have white-label branding configured.
• You receive no invoice or confirmation email, because nothing was charged.

{
  "scope_used": "partner.checkout.write",
  "warnings": [],
  "customer_id": 192601,
  "address_id": null,
  "subscription_id": 88214,
  "subscription_trial_id": 26411,
  "customer_email": "alice@example.com",
  "company": {
    "legal_name": "Sunrise Hospitality Pty Ltd",
    "abn": "10000000000",
    "ird_number": null,
    "country_code": "AU",
    "currency_code": "AUD"
  },
  "trial_start_date": "2026-07-31",
  "trial_expiry": "2026-08-31",
  "days_remaining": 31,
  "site_mode": "au",
  "emails_sent": true,
  "idempotency_replayed": false
}

10. List trials

Paginated list of the trials you created, newest first. Accepts any partner checkout scope.

Each row returns subscription_trial_id, subscription_id, customer_id, customer_email, company_name, status, trial_start_date, trial_expiry, days_remaining, cancelled_at, converted, and converted_order_id.

• status is active while the trial runs, cancelled if you ended it early, and expired once it lapsed on its own.
• days_remaining is zero or negative once the trial has ended.
• converted is true once you have placed a paid order for that client, and converted_order_id names it.
• Trials that started on our own website are not listed, because they are not yours.

11. Cancel a trial

Ends a trial before its expiry date, for example when it was provisioned against the wrong entity. Requires partner.checkout.cancel or partner.checkout.write.

{
  "subscription_trial_id": 26411,
  "reason": "Provisioned against the wrong entity."
}

Rules:

• You may only cancel a trial you created (403 otherwise), and an unknown ID returns 404.
• Cancelling twice returns 409.
• The trial subscription's expiry is set to yesterday, so the client's access ends immediately.
• The client record and the trial history are kept for audit; nothing is deleted.
• Cancelling does not release the company's claimed ABN or IRD number, because that record can carry live accounting-integration connections. If you need to re-provision the same company under a different email address, contact support.

{
  "subscription_trial_id": 26411,
  "subscription_id": 88214,
  "customer_id": 192601,
  "previous_trial_expiry": "2026-08-31",
  "trial_expiry": "2026-07-30",
  "cancelled_at": "2026-07-31T02:14:09",
  "reason": "Provisioned against the wrong entity."
}

08Managing renewals and ending a subscription

Upgrades move a client up a tier immediately. Moving a client down a tier works differently: a mid-term downgrade is rejected at checkout, because a part-used higher plan is worth more than the lower plan being bought. What you can set is the plan a client renews onto.

For clients whose headcount moves seasonally, put them on a monthly billing cycle. Monthly does not change the downgrade rule, but it means a renewal comes around every month rather than once a year, so a client can move up when they need to and back down at the end of the month.

12. List upcoming renewals

Lists every client subscription you onboarded that has not yet renewed, oldest expiry first. Query parameters: limit (default 50, max 200), offset.

Each entry carries the current plan, is_monthly, auto_renew_on, will_auto_renew, renewal_state, the order_id and order_status_id of the order the subscription was sold on, and pending_renewal.

pending_renewal is null until a renewal order has been prepared. Those are created 30 days before expiry for annual subscriptions, and same-day as the previous renewal for monthly ones, so a monthly client has one you can change from their first renewal on. Check it is non-null, and that its editable flag is true, before calling the update below.

Whether a subscription will renew:

• will_auto_renew is true only when the subscription will be renewed at expiry, subject to payment. Rely on it rather than auto_renew_on.
• auto_renew_on is the client's preference. It is stored per customer, so it stays true on a subscription that cannot renew.
• renewal_state gives the reason. The first that applies is reported: superseded, trial, lapsed (expiry has passed), no_order, order_cancelled (the order it was sold on is cancelled), order_not_complete, renewal_cancelled (its prepared renewal order is no longer pending), renewal_not_prepared (no renewal order exists and none will be prepared before expiry: an annual subscription inside 30 days of expiry; contact support if it should renew), auto_renew_off, will_renew. Treat a value you do not recognise as not renewing.
• A subscription sold on an order that was later cancelled is still listed, with renewal_state order_cancelled. Only a subscription sold on a complete order (order_status_id 5) renews.
• editable is false unless the renewal order is still pending, the subscription was sold on a complete order, and it has not lapsed. An auto_renew_off subscription stays editable, since the same update can switch automatic renewal back on.

13. Change a pending renewal

Sets the plan a client renews onto, and whether they renew at all. Supply at least one field.

{
  "renewal_product_id": 280,
  "auto_renew_on": true,
  "send_renewal_notification": true
}

Business rules:

• The subscription must be one your account onboarded, else 403.
• renewal_product_id edits the pending renewal order, so 409 if none exists yet or it is no longer pending.
• renewal_product_id is 409 on a subscription that will not renew: one sold on an order that is cancelled or not complete, or one that has lapsed. Its renewal line is never charged, so changing it achieves nothing. To put the client back on a plan, place a new order with end_customer_id. See "Ordering for an existing client".
• The product must be one of your own subscription plans; add-ons, ad-hoc products and discount products are 422.
• The line's price and tax resolve from the renewal order's billing country, falling back to your account's billing address; 409 if neither resolves to AU or NZ.
• The line is repriced at your negotiated reseller rate.
• Per-employee quantity is kept as it is, unless it falls below the client's per_employee_minimum (default 15), in which case it is raised to that floor.
• auto_renew_on is stored against the end customer, so it applies to every subscription that customer holds. The response lists each affected subscription in auto_renew_affects_subscription_ids. It can still be set on a subscription that will not renew.
• The response's will_auto_renew and renewal_state report whether the subscription you passed will renew after the change.
• A short notification is emailed to you whenever the line actually changes. Set send_renewal_notification to false to suppress it, for example when your own users drive the change.

No Idempotency-Key is needed. Editing an existing renewal line is idempotent by construction.

14. End a subscription early

Ends a client's paid subscription now, before its expiry date. The subscription's expiry is set to yesterday, so the client's access ends straight away and their data becomes read-only unless they hold another subscription. Requires partner.checkout.cancel or partner.checkout.write; a dry run also accepts partner.checkout.preview.

This is the only call that gives up paid time, so dry_run is required, with no default. Preview first: a dry run changes nothing and reports exactly what would end.

{
  "subscription_id": 98321,
  "dry_run": true,
  "reason": "Client has stopped trading."
}

Choose the right call for what you want:

• Move the client to another plan: use POST /api/partner-checkout/upgrades. An upgrade credits the unused value of the current subscription; ending it and placing a new order does not.
• Stop the client renewing at the end of their term: set auto_renew_on to false with PATCH /api/partner-checkout/renewals/{subscription_id}. Access continues until the expiry date.
• Reverse a sale placed in error: within 60 days of the order, POST /api/partner-checkout/orders/cancel voids the charge, and with end_subscription: true also ends the access that order sold. Ending the subscription does not void the charge.
• End a free trial: use POST /api/partner-checkout/trials/cancel.

Rules:

• Nothing is refunded or credited. refund_or_credit_issued is always false, and remaining_days_forfeited counts the paid days given up, from today through the old expiry. The order the subscription was sold on keeps its status and totals, and you are still billed for it.
• The subscription must be the current one, sold on an order your account placed (403 otherwise). One that has been renewed or upgraded returns 409 naming the subscription that replaced it, which is the one to end.
• A subscription sold on an order you already cancelled can be ended too, since nothing was billed for it. Cancelling an order without end_subscription: true leaves the client's access running until the expiry date.
• Any subscription this one replaced through an upgrade or renewal that still had access running is ended with it, because its value was carried into this one. Each is listed in ended_subscription_ids.
• A pending renewal order is cancelled so the subscription is not renewed or billed again, and listed in voided_renewal_order_ids.
• A subscription sold on a base or both-mode upgrade order that can still be cancelled returns 409 while the subscription the upgrade replaced still has time to run: ending it would end that one too and forfeit its time. Cancel the upgrade order with end_subscription: true instead, which restores the replaced subscription with its own expiry, then end that one if the client should lose access.
• The client's add-ons lapse with the subscription, including add-ons sold on a separate add-on upgrade order. That order is not cancelled and stays billed, so warnings names it with the date its own cancellation window closes. Their auto_renew_on preference, account and data are left as they are, and no email is sent.
• An audit note recording who ended it, the old expiry and your reason is added to the order's history.
• A free trial returns 409 with its subscription_trial_id; an unknown ID returns 404; one that has already ended returns 409. A repeated call is therefore 409, so no Idempotency-Key is needed.
• warnings tells you when the order is still inside its 60-day cancellation window, and, on a dry run, that an upgrade would credit the unused time.

{
  "mode": "execute",
  "dry_run": false,
  "scope_used": "partner.checkout.cancel",
  "subscription_id": 98321,
  "customer_id": 192601,
  "order_id": 192484,
  "order_status_id": 5,
  "previous_expiry": "2027-08-31",
  "expiry": "2026-10-05",
  "ended_at": "2026-10-06T02:14:09",
  "remaining_days_forfeited": 330,
  "refund_or_credit_issued": false,
  "ended_subscription_ids": [98321],
  "voided_renewal_order_ids": [],
  "has_active_subscription": false,
  "other_active_subscription_ids": [],
  "reason": "Client has stopped trading.",
  "warnings": []
}

A dry run returns the same shape with mode preview, ended_at null, and the values the call would produce.

09Looking up and updating a client

15. Resolve a client

Resolves a customer id into who that client is and whether they are currently subscribed. Requires any partner checkout scope.

Use it to turn the customerId on a webhook payload, or one you stored at onboarding, into a name, an email and the plans the client holds right now.

You can look up three kinds of client: clients you onboarded through partner checkout, clients you started on a free trial, and clients who have authorised your OAuth client.

The last case is the one that matters if your integration connects to customers who already subscribe rather than selling to them. Those clients have no order attributed to you, but a live authorisation is enough on its own. Any other customer id returns 404, whether or not it exists, so this cannot be used to discover ids you were not already given.

Cancelling a trial or an order, or ending a subscription, does not end the relationship, so those clients remain visible.

{
  "customer_id": 12345,
  "customer_name": "Alice Nguyen",
  "company_name": "Acme Pty Ltd",
  "email": "alice@example.com",
  "has_active_subscription": true,
  "subscriptions": [
    {
      "subscription_id": 987,
      "product_id": 240,
      "product_name": "Enterprise",
      "expiry": "2027-03-01",
      "status": "active",
      "is_monthly": false,
      "is_trial": false,
      "auto_renew_on": true,
      "quantity": 15,
      "will_auto_renew": true,
      "renewal_state": "will_renew",
      "order_id": 45678,
      "order_status_id": 5
    }
  ]
}

Notes:

• has_active_subscription is the same check that decides whether a client's data is writable. When it is false, reads keep working but writes return 403, so testing this first separates a lapsed client from a genuine fault in your integration.
• subscriptions lists the current term of each subscription, latest expiry first. It is empty for a client who has never subscribed.
• status becomes lapsed on the day after expiry. A subscription expiring today is still active. It describes access, not renewal: an active subscription may still not renew.
• will_auto_renew says whether the subscription will renew at expiry, and renewal_state says why not when it will not. Both carry the same meaning as on the renewals list in section 08. A subscription sold on an order that was later cancelled reads active until it expires, with renewal_state order_cancelled.
• order_id and order_status_id identify the order the subscription was sold on, when your account placed it. They are null on a trial, and on a subscription the client bought through another channel. On the latter renewal_state is null too, since it is worked out from that order; will_auto_renew still says whether it renews.
• is_trial marks a free trial. A trial reads as active right up until it ends, so check this flag before treating a client as a paying customer.
• A trial was never sold, so it has no order line behind it. On a trial, product_id, product_name, quantity and is_monthly are all null. Treat is_trial as the reason those fields are missing, rather than expecting a product.
• auto_renew_on is the client's preference, stored against the customer rather than the subscription, so every entry carries the same value, including one that will not renew.

Access to this endpoint is not a substitute for the webhook stream. It answers "what is this client's state now", not "what changed".

16. Update a client's contact details

Corrects a client's first name, last name, phone number or login email. Requires partner.checkout.write. Send only the fields you want to change, and at least one.

{
  "first_name": "Alice",
  "last_name": "Nguyen",
  "email": "alice.nguyen@example.com",
  "phone": "+61 7 3000 0000"
}

{
  "customer_id": 12345,
  "first_name": "Alice",
  "last_name": "Nguyen",
  "email": "alice.nguyen@example.com",
  "phone": "+61 7 3000 0000",
  "changed_fields": ["email"],
  "email_changed": true,
  "previous_email_notified": true
}

Business rules:

• You can update clients you onboarded through partner checkout and clients you started on a free trial. Clients who have only authorised your OAuth client can be looked up above but not updated, because connecting your app does not hand you their account. Any other customer id returns 404, whether or not it exists.
• An email already used by another account returns 409. A change of letter case alone is stored, but is not treated as a login change.
• changed_fields lists only the fields whose stored value actually changed, so repeating a call is harmless. No Idempotency-Key is needed.

Changing email moves the client's login, immediately. When it changes:

• The previous address is emailed that the login changed. previous_email_notified reports whether that notice was queued.
• Any password reset or onboarding link already sent to the previous address stops working.
• The new address is emailed that it is now the login.
• No new onboarding link is sent. If the client has not onboarded yet, call POST /api/partner-checkout/orders/{order_id}/resend-onboarding-link (endpoint 8) afterwards so the link reaches the new address.
• If the client uses the desktop app, they must enter the new email under Tools > Licence Assistant before its licence check passes again.

10Idempotency

Idempotency only applies to order and upgrade execute requests where dry_run=false, and to trial creation.

• Idempotency-Key is required.
• Maximum length is 255.
• Same key plus same payload returns the original successful execute response with idempotency_replayed=true.
• A successful claim remains replayable with the same key and payload after its trial has been retired; do not generate a new key merely because a response timed out.
• Same key plus different payload returns 409.
• Keys are shared across orders, upgrades and trials, so do not reuse an order's key for a trial or an upgrade.
• Cancelling an order or a trial, ending a subscription, and changing a renewal or a client's contact details take no key. Repeating a cancel or an end returns 409, and repeating a change alters nothing further.

11Pricing and promo behaviour

• Australia uses AUD.
• New Zealand uses NZD.
• /options can show both partner pricing and mapped retail RRP values.
• Preview and execute responses can include a welcome-offer promo discount on the base subscription line.
• Preview and execute responses return identical order_lines and totals for the same payload: preview is the price the partner agrees to, and execute persists those exact numbers.

Per-line GST and RRP disclosure

Every entry in order_lines includes the GST treatment that was applied and, where available, the retail comparison values:

The numeric advertised price is the same; the GST treatment differs.

12Subscription term alignment & prorating

Partners often need a new Lightning Payroll subscription to expire on the same date as the partner's own renewal cycle. Supply order.subscription_end_date to align the term and have the base subscription and recurring add-ons prorated to that window.

Rules:

• subscription_end_date must be strictly after today.
• For annual base products it must be less than 365 days from today.
• For monthly base products it must be less than 30 days from today.
• Out-of-range values are rejected with 422.
• A training session line, when requested via order.include_training_session, is always charged at full retail; it is one-off labour, not a recurring service.
• The aligned date is recorded as the subscription's exact expiry; the next term renews at full price under normal renewal rules.

Prorata formula

paid_days  = (subscription_end_date - today) - (30 if add_free_trial_month else 0)
factor     = max(0, paid_days) / term_days     # term_days = 365 annual, 30 monthly
unit_price = round(base_after_reseller_discount * factor)   # NZ uplift applied after

If paid_days <= 0 (e.g. a partner aligning a customer for a window smaller than the free trial month) the prorated lines are charged $0. A requested training session line remains at full price regardless.

Response fields

• subscription_end_date: echoed when supplied, null otherwise.
• prorata_factor: the multiplier applied to prorated lines, null when no alignment was requested.
• warnings: includes a description of the prorata factor and any $0-floor or trial-month-consumed notes.

13Email behaviour

On successful execute:

• The authenticated reseller receives a billed-account confirmation email.
• If oauth_onboarding was supplied, the new customer receives a branded magic onboarding email (see "OAuth single-flow onboarding"); this replaces the password-reset welcome email.
• Otherwise, if send_customer_welcome_email=true, the new customer receives a branded onboarding email with a password-reset link.
• An existing-trial claim always queues a separate mandatory customer notice, regardless of send_customer_welcome_email. Its durable delivery status is operational state and is not represented by emails_sent.

If email sending fails, the order can still succeed and emails_sent will be false.

If onboarding or the OAuth connection needs recovery, call POST /api/partner-checkout/orders/{order_id}/resend-onboarding-link (endpoint 8). It safely chooses a fresh magic link or normal sign-in and reauthorization. Unlike execute, a recovery whose email fails returns 502 and issues no new magic link.

14Error reference

15Production checklist

16Related guides