Billing Operations
Part of Subscription billing operations
Distinguishing a billing retry from a new order
Trace the intended cycle, payment attempts and order records to recognise a recovered charge and investigate duplicates.
A billing retry is another attempt to collect for an intended subscription cycle. An order is the purchase record that may result when an attempt succeeds. The two are not mutually exclusive: a successful retry can create an order for the original cycle. First identify the cycle being collected, then decide whether an order represents that cycle, a later renewal or a separate purchase.
Trace the intended delivery
Start with the subscription contract and the delivery the original charge was meant to fund. Compare its cycle reference, expected amount, attempt history, collected payment and order reference. Where the provider supplies a reference shared across retried attempts, retain it.
A later timestamp or a newly created order ID does not by itself mean a new customer purchase.
In Shopify's documented API, a successful subscription billing attempt creates an order. A billing-attempt record can include the contract, transactions and a payment-group reference shared between retried attempts. These are Shopify-specific fields; some fields on the documented resource are deprecated, so confirm the current integration before relying on an individual field.
Tracing the intended delivery before classifying an order
- Start with the subscription contractIdentify the delivery the original charge was meant to fund.
- Compare the cycle referenceMatch the cycle reference on the contract against the attempt and the order.
- Compare the expected amountCheck the expected amount against the collected payment.
- Retain any shared attempt referenceThe documented billing-attempt record can include a payment-group reference shared between retried attempts.
- Note that a successful attempt creates an orderA later timestamp or a new order ID does not by itself mean a new customer purchase.
Classify the records separately
| Record pattern | What it may mean | Check before acting |
|---|---|---|
| Earlier attempt fails; later attempt succeeds for the same intended cycle | Recovered cycle, potentially with an order created on success | Confirm the collected payment and resulting order |
| A later scheduled cycle has its own delivery commitment | New recurring cycle | Confirm its schedule, charge and parcel |
| The customer completes another checkout | Separate purchase | Confirm authorisation and check for duplicate fulfilment |
| Two charges or orders appear for one intended delivery | Possible duplicate or adjustment | Inspect both records before packing or refunding |
A provider may create no order on a failed attempt or may retain an unpaid order. Count attempts, payments, orders and deliveries separately; none of those counts alone identifies a new sale.
Prevent duplicate collection and packing
Before manually retrying a charge or creating an order, look for a pending attempt, collected payment and existing order for the intended cycle.
Shopify's billing-attempt creation API accepts an idempotency key so a repeated request can execute once and avoid duplicate charges. Use that safeguard according to the provider's documentation; it does not replace checking for a different earlier request or manual charge.
Carry the cycle reference into fulfilment so recovery releases the parcel originally due. If a second order appears, hold it while checking whether the customer authorised an extra purchase or an operation created a duplicate.
Checks before manually retrying a charge or creating an order
- Look for a pending attempt on the intended cycle
- Look for a collected payment on the intended cycle
- Look for an existing order covering that cycle
- Use an idempotency key so a repeated request can execute once and avoid duplicate charges
- Check for a different earlier request or manual chargean idempotency key does not replace that check
- Carry the cycle reference into fulfilment so recovery releases the parcel originally due
- If a second order appears, hold it while checking whether the customer authorised an extra purchase or an operation created a duplicate
Record the outcome
For the intended cycle, show whether payment was collected, remains unresolved or ended under the plan's rule, and which order or parcel follows. If recovery missed the packing cutoff, give the revised dispatch expectation. Keep failed attempts visible without counting each as another sale.
What to record for the intended cycle
- Whether payment was collected
- Whether payment remains unresolved
- Whether it ended under the plan's rule
- Which order or parcel follows
- A revised dispatch expectation if recovery missed the packing cutoff
- Failed attempts kept visible without counting each as another sale
