--- title: "Create an allocation payment" method: POST path: "/allocation-payment" tags: ["Allocation payments"] --- # Create an allocation payment `POST /allocation-payment` Creates an allocation payment. ## Headers - `Accept` 'application/vnd.Creative Force.v2.3+json' | 'application/vnd.Creative Force.v2.3+xml', required - `x-api-language` string[] ## Request body - object - `allocation` string, required — Slug of the allocation the payment is drawn against. - `amount` number, required — Amount of the payment, in the currency of the allocation's fund. Cannot exceed the allocation's unscheduled balance. - `date_due` string, nullable — Date the payment is due. Accepts `Y-m-d` or `Y-m-d\TH:i:s\Z` format. - `date_paid` string, nullable — Date the payment was made. Accepts `Y-m-d` or `Y-m-d\TH:i:s\Z` format. Required when `status` is `paid`. - `external_id` string, nullable — External identifier of the payment, used to reconcile it with downstream systems. - `payment_method` string, nullable — Slug of the payment method. - `reference` string, nullable — Free-text reference for the payment. - `status` 'failed' | 'failed_permanently' | 'paid' | 'processing' | 'scheduled', required — Lifecycle status of the payment. ## Response `201` Allocation payment created. - AllocationPayment — Additional allocation payment fields returned only for a single allocation payment. - `allocation` object — Allocation the payment is drawn against. - `slug` string — URL-safe identifier of the allocation. - `link` string, uri — Canonical URL of the allocation resource. - `amount` number — Amount of the payment, in the fund's currency. - `comments` string — Comment log attached to the payment, rendered as a newline-joined export string of `author (timestamp): body` entries. Empty string when the payment has no comments. - `created` string, date-time — Date and time when the payment was created. - `currency` string — ISO 4217 currency code of the payment's amounts, drawn from the fund's currency. - `date_due` string, date-time, nullable — Date and time when the payment is due. `null` when no due date is set. - `date_paid` string, date-time, nullable — Date and time when the payment was made. `null` when the payment has not been made. - `external_id` string — External identifier of the payment, used to reconcile it with downstream systems. Empty string when none is set. - `grant_status` object, nullable — Grant status of the entry the allocation belongs to. Present only when the grants feature is enabled on the account. `null` when the entry has no grant status. - `slug` string — URL-safe identifier of the grant status. - `link` string, uri — Canonical URL of the grant status resource. - `name` object — Name of the grant status. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - `payment_method` object, nullable — Payment method recorded against the payment. `null` when no payment method is set. - `slug` string — URL-safe identifier of the payment method. - `link` string, uri — Canonical URL of the payment method resource. - `name` object — Name of the payment method. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - `reference` string — Free-text reference for the payment. Empty string when none is set. - `season` object — Season the payment belongs to. - `slug` string — URL-safe identifier of the season. - `link` string, uri — Canonical URL of the season resource. - `name` object — Name of the season. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - `slug` string — URL-safe identifier of the payment. - `status` string — Lifecycle status of the payment, returned as a localised label rendered in the account's language. Typical English labels are `Scheduled`, `Processing`, `Paid`, `Failed`, and `Failed permanently`. - `updated` string, date-time — Date and time when the payment was last updated. - `allocation_amount` number — Total amount of the allocation the payment is drawn against, in the fund's currency. - `entrant` object, nullable — Entrant who owns the entry the allocation belongs to. Emitted as an empty array when the entry has no entrant. - `slug` string — URL-safe identifier of the entrant. - `link` string, uri — Canonical URL of the entrant resource. - `name` string — Full display name of the entrant. - `first_name` string — Given name of the entrant. - `last_name` string — Family name of the entrant. - `email` string — Email address of the entrant. - `global_id` string — Account-independent identifier of the entrant. - `entry` object, nullable — Entry the allocation belongs to. Emitted as an empty array when the payment has no associated entry. - `slug` string — URL-safe identifier of the entry. - `id` integer — Internal numeric identifier of the entry. - `title` string — Title of the entry as submitted by the entrant. - `link` string, uri — Canonical URL of the entry resource. - `fund` object — Fund the allocation draws from. - `slug` string — URL-safe identifier of the fund. - `link` string, uri — Canonical URL of the fund resource. - `name` object — Name of the fund. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. ## Other responses - `400` — Request was rejected before the endpoint could process it. Common causes: invalid `Accept` header, unsupported `x-api-language` code, empty request body on `POST` / `PUT`, invalid JSON in the request body, or an invalid slug format in a path parameter. - `401` — Missing `x-api-key` header. - `403` — Authenticated request denied. Common causes: invalid or unknown API key, suspended account, or `api` feature not enabled for the account. - `422` — Request was syntactically valid but could not be processed. Returned in two scenarios: - **Field-level validation failure** — one or more request fields violated the endpoint's validation rules. The body includes an `errors` map keyed by field name with one or more validation messages each. - **Resource-state precondition failure** — the request fields were all valid, but the target resource was in a state that does not permit the requested operation. The body carries only `message` and `status_code`; no `errors` map. - `429` — Rate limit of 60 requests per minute exceeded. - `503` — Service is temporarily unavailable due to regional maintenance. ## Changes - **2026-07-07** (v2) `9b9103538ceb` — 2 info - api tag `Allocation payments` added - api tag `Allocation payment` removed - **2026-07-01** (v2) `e96a96d4507e` — 7 info - added the media type `application/xml` for the response with the status `201` - added the media type `application/xml` for the response with the status `400` - added the media type `application/xml` for the response with the status `401` - added the media type `application/xml` for the response with the status `403` - …3 more - **2026-06-30** (v2) `7d50c26b06f7` — 1 info - endpoint added [Change history](https://skmtc.dev/tectonic/apis/award-force-api/changes/allocation-payment/post.md) --- [API](https://skmtc.dev/tectonic/apis/award-force-api.md) · [All operations](https://skmtc.dev/tectonic/apis/award-force-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tectonic/award-force-api/revisions/9b9103538ceb/schema)