# Boostsy API idempotent order submission workflow

Generate and persist one unique reference for one intended order before the first add request. Reuse that reference and the original payload when retrying an ambiguous submission. A new reference represents a new order and can create a second wallet charge.

## Example add request body

{
  "action": "add",
  "service": "YOUR_SELECTED_SERVICE_ID",
  "link": "https://example.com/public-target",
  "quantity": 100,
  "idempotency_key": "YOUR_STORED_UNIQUE_REFERENCE"
}

POST to https://boostsy.net/api/v2 with server-side authentication. This illustrative target and quantity must be replaced with a valid target and quantity for the actual selected service.

## Alternative request header

Idempotency-Key: YOUR_STORED_UNIQUE_REFERENCE

The header is supported and takes precedence over the body field. Use one consistent source; conflicting values make your own records harder to reconcile.

## Illustrative accepted response

{"order":"o0123456789abcdef01234567"}

Store the returned opaque string exactly. This sample is not a live order. An accepted order is queued and charged; acceptance does not mean delivery has completed.

## Persist before sending

Create the intent: Store the chosen service, exact public target, quantity and unique request reference together.

Send add: Use the stored reference in the header or body, with the intended payload.

Save the order ID: Attach the accepted ID to the intent; further status work uses that ID.

Recover ambiguity: After a timeout, retry the original intent with its original reference rather than creating another intent.

## Choose the recovery action

"Situation","Action","Reason"
"Accepted response received","Save the ID and switch to status","The order already exists"
"Timeout with acceptance unknown","Retry the original payload and reference","The server may have accepted the first request"
"Same reference submitted again","Expect the original account-owned order ID","The existing reference is returned without a second charge"
"Customer wants another order","Create a new intent with a new reference","This is a distinct purchase decision"
"Payload needs changing after ambiguous submission","Reconcile the original first","Reusing the reference does not edit an existing order"


## Implementation checks

- [ ] Persist the reference before making the network request.

- [ ] Keep retries on the same stored intent and payload.

- [ ] Treat order and service IDs as opaque strings.

- [ ] Keep API credentials on the server and redact them from logs.

- [ ] Do not generate a new reference simply because a response was delayed.

## Important request behaviour

If you omit both supported idempotency fields, the API supplies a new reference. That cannot protect two independently sent requests from creating two orders. Your integration must preserve the reference across retries.

For an existing account-owned reference, the handler returns the previous order ID before revalidating the new service payload. Reusing a reference with changed fields is not an update operation. Bind the reference to an immutable intent in your own records.

Read current service parameters and ensure the wallet and selected service can support the intended order. These examples do not submit anything, and their sample price or quantity is not an offer.