Update a contract

PATCH/v1/contracts/{reference}

Edits the bookkeeping on one of your agreements: the order reference your own systems know it by, and your metadata. Nothing else on a contract is writable.

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

Request

Parameter	In	Notes
reference	path	The agreement's public reference.
order_reference	body	Optional. Your own id for the order, up to 100 characters.
metadata	body	Optional. Up to 50 string key/value pairs. Replaces the stored map wholesale; send null to clear it.

curlPHPPHP SDKJS/TS SDK

curl -X PATCH "$SHOTPAY_URL/v1/contracts/LAY-8F2KQ0MZXA" \
  -H "X-Client-Id: $SHOTPAY_CLIENT_ID" \
  -H "X-Api-Key: $SHOTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_reference": "SO-2026-0042", "metadata": {"crm_id": "77"}}'

$contract = Http::withHeaders([
    'X-Client-Id' => config('shotpay.client_id'),
    'X-Api-Key' => config('shotpay.api_key'),
])->patch(config('shotpay.url')."/v1/contracts/{$reference}", [
    'order_reference' => 'SO-2026-0042',
    'metadata' => ['crm_id' => '77'],
])->json('data');

$contract = $client->contracts->update($reference, [
    'order_reference' => 'SO-2026-0042',
    'metadata' => ['crm_id' => '77'],
]);

const contract = await client.contracts.update(reference, {
    order_reference: 'SO-2026-0042',
    metadata: { crm_id: '77' },
});

Response

200 OK — the updated Contract, in the same shape as retrieving one.

{
  "data": { "…": "…" }
}

Errors

Status	When
401	The header pair did not authenticate.
403	The key is missing the contracts:write scope, or the account is not active.
404	No agreement of yours, in this mode, has that reference.
422	A metadata key or value breaks the caps, or metadata arrived as a list.
429	Rate limited. Back off for Retry-After seconds.

See Error Handling.