Skip to content

Retrieve a contract

GET/v1/contracts/{reference}

One agreement with its full schedule, addressed by the reference every contract and installment webhook carries.

Authentication — X-Client-Id and X-Api-Key, with the contracts:read scope.

Request

Parameter In Notes
reference path The agreement's public reference, e.g. LAY-8F2KQ0MZXA. 
curl "$SHOTPAY_URL/v1/contracts/LAY-8F2KQ0MZXA" \
  -H "X-Client-Id: $SHOTPAY_CLIENT_ID" \
  -H "X-Api-Key: $SHOTPAY_API_KEY"

$contract = Http::withHeaders([
    'X-Client-Id' => config('shotpay.client_id'),
    'X-Api-Key' => config('shotpay.api_key'),
])->get(config('shotpay.url')."/v1/contracts/{$reference}")->json('data');

$contract = $client->contracts->retrieve($reference);

const contract = await client.contracts.retrieve(reference);

Response

200 OK — a Contract.

{
  "data": {
    "reference": "LAY-8F2KQ0MZXA",
    "order_reference": "SO-2026-0042",
    "status": "active",
    "customer_name": "Avery Quinn",
    "customer_email": "avery@example.com",
    "customer_state": "TX",
    "total_amount": 100000,
    "reservation_fee_amount": 5000,
    "customer_total": 105000,
    "down_payment_amount": 30000,
    "paid_amount": 30000,
    "remaining_amount": 75000,
    "installments": [
      { "sequence": 1, "type": "cart_capture", "installment_number": null, "amount": 30000, "due_date": "2026-07-01", "status": "paid", "paid_at": "2026-07-01T16:21:00+00:00" },
      { "sequence": 2, "type": "installment_capture", "installment_number": 1, "amount": 25000, "due_date": "2026-07-15", "status": "upcoming", "paid_at": null }
    ],
    "started_at": "2026-07-01T16:20:00+00:00",
    "completed_at": null,
    "defaulted_at": null,
    "cancelled_at": null,
    "created_at": "2026-07-01T16:20:00+00:00",
    "metadata": { "crm_id": "77" }
  }
}

Errors

Status When
401 The header pair did not authenticate.
403 The key is missing the contracts:read scope, or the account is not active.
404 No agreement of yours, in this mode, has that reference.
429 Rate limited. Back off for Retry-After seconds.

See Error Handling.