> ## Documentation Index > Fetch the complete documentation index at: https://docs.rigaly.com/llms.txt > Use this file to discover all available pages before exploring further. # Update fulfillment status > Advances a shipping redemption through its lifecycle. `id` is the redemption's `id` from the list endpoint (not the 8-character code). - `shipped` — stamps `shipped_at`. Send `tracking_reference` with it so the customer can follow the parcel in the app. - `delivered` — stamps `delivered_at`, and backfills `shipped_at` if you skipped the shipped step. - `cancelled` — **refunds the customer's points by default**, moves the redemption's `status` to `cancelled`, and releases the reward's redemption slot (a reward that its cap had closed reopens). Send `refund_points: false` to cancel without paying the points back. The refund and the status transition happen in a single database function, so cancelling is **atomic and idempotent**: a retry of the same cancel pays out nothing a second time. Billing is deliberately *not* reversed — the per-transaction fee charged for the original claim stands. `tracking_reference: ""` is stored as `null`. ## OpenAPI ````yaml /openapi/v1.yaml patch /api/v1/redemptions/{id}/fulfillment openapi: 3.1.0 info: title: Rigaly Business API version: '1.0' description: | Public API for businesses to manage their Rigaly loyalty programs: issue and redeem points, manage rewards, validate redemptions, and generate mass codes for physical products. All endpoints require an API key created in the Rigaly business dashboard (Tools → API Management), passed as `Authorization: Bearer rgly_sk_...`. contact: email: support@rigaly.com servers: - url: https://api.rigaly.com description: Production security: - apiKey: [] paths: /api/v1/redemptions/{id}/fulfillment: patch: tags: - Redemptions summary: Update fulfillment status description: > Advances a shipping redemption through its lifecycle. `id` is the redemption's `id` from the list endpoint (not the 8-character code). - `shipped` — stamps `shipped_at`. Send `tracking_reference` with it so the customer can follow the parcel in the app. - `delivered` — stamps `delivered_at`, and backfills `shipped_at` if you skipped the shipped step. - `cancelled` — **refunds the customer's points by default**, moves the redemption's `status` to `cancelled`, and releases the reward's redemption slot (a reward that its cap had closed reopens). Send `refund_points: false` to cancel without paying the points back. The refund and the status transition happen in a single database function, so cancelling is **atomic and idempotent**: a retry of the same cancel pays out nothing a second time. Billing is deliberately *not* reversed — the per-transaction fee charged for the original claim stands. `tracking_reference: ""` is stored as `null`. operationId: updateRedemptionFulfillment parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - shipped - delivered - cancelled tracking_reference: type: string maxLength: 255 nullable: true example: 1Z999AA10123456784 refund_points: type: boolean default: true description: | Only read when `status` is `cancelled`. Defaults to `true`: the points the customer spent are credited straight back to their balance. Send `false` to cancel without a refund — for example when you have already settled with the customer some other way, or the goods were delivered and later returned under your own returns policy. example: status: shipped tracking_reference: 1Z999AA10123456784 responses: '200': description: Fulfillment updated content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: redemption: allOf: - $ref: '#/components/schemas/FulfillmentRedemption' - type: object properties: points_refunded: type: integer nullable: true example: 5000 description: | Points credited back to the customer by this call. Always `null` on `shipped` and `delivered`. On `cancelled` it is `null` when you sent `refund_points: false`, and when nothing was owed — a free reward, an anonymised customer, or a redemption that is no longer `completed` (already cancelled, so an earlier call already paid it out). '400': description: | Validation error; the redemption is not a shipping one (`REDEMPTION_NOT_SHIPPABLE`); or the points refund failed (`Failed to refund redemption points: …`). The refund runs before the fulfillment row is written, so on a refund failure **nothing is applied** — no points move and the status is unchanged. Retry the same request. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: notShippable: summary: Not a shipping redemption value: success: false error: message: REDEMPTION_NOT_SHIPPABLE refundFailed: summary: Refund could not be paid out — nothing was applied value: success: false error: message: 'Failed to refund redemption points: deadlock detected' '404': $ref: '#/components/responses/NotFound' '409': description: >- The redemption was already cancelled (`FULFILLMENT_ALREADY_CANCELLED`) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: message: FULFILLMENT_ALREADY_CANCELLED components: parameters: ResourceId: name: id in: path required: true schema: type: string format: uuid schemas: SuccessEnvelope: type: object properties: success: type: boolean example: true message: type: string data: type: object FulfillmentRedemption: type: object description: >- A shipping-mode redemption awaiting (or past) fulfillment. Points were already deducted when the customer redeemed. properties: id: type: string format: uuid description: Use this id with the fulfillment endpoint. code: type: string example: AB12CD34 status: type: string enum: - pending - completed - expired - cancelled example: completed description: >- `completed` while the order is live. Cancelling the fulfillment moves it to `cancelled`, which frees the reward's redemption slot. fulfillment_status: $ref: '#/components/schemas/FulfillmentStatus' created_at: type: string format: date-time description: When the customer redeemed. shipped_at: type: string format: date-time nullable: true delivered_at: type: string format: date-time nullable: true tracking_reference: type: string nullable: true example: 1Z999AA10123456784 ship_to_name: type: string nullable: true example: Jane Doe ship_to_phone: type: string nullable: true example: '+15551234567' ship_to_email: type: string nullable: true example: jane@example.com ship_to_address: type: string nullable: true example: 123 Main St, Springfield, IL 62704 reward_id: type: string format: uuid reward_name: type: string example: Limited edition shirt reward_image_url: type: string nullable: true points_cost: type: integer example: 5000 user_id: type: string format: uuid nullable: true user_name: type: string nullable: true example: Jane Doe ErrorEnvelope: type: object properties: success: type: boolean example: false error: type: object properties: message: type: string FulfillmentStatus: type: string nullable: true enum: - pending - shipped - delivered - cancelled example: pending description: | Shipping lifecycle of a redemption. `null` for in-store and digital rewards — only shipping redemptions carry one. `pending` (awaiting fulfillment) → `shipped` → `delivered`, or `cancelled` at any point before delivery. responses: NotFound: description: Resource not found (or belongs to another business) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: message: Reward not found securitySchemes: apiKey: type: http scheme: bearer description: 'API key from the Rigaly dashboard: `Authorization: Bearer rgly_sk_...`' ````