Orders

POST /orders/[playerId]/reservation

Creates a reservation for a product tied to a specific player and establishment. This can be used to hold inventory before full checkout or confirmation.

Endpoint

POST/orders/{playerId}/reservation

Request Body

{
  "productId": "00000000-0000-0000-0000-000000000000",
  "establishmentId": "00000000-0000-0000-0000-000000000000",
  "email": "name@example.com",
  "denomination": 0
}

Attribute	Type	Required
productId	string(uuid)	Yes
establishmentId	string(uuid)	Yes
email	string(email)	No
denomination	integer	No

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes

Responses

200

Reservation successfully created.

{
  "operationId": "c51c4418-49a3-404f-b811-cfbb4e0a3619",
  "orderType": "Reservation",
  "orderStatus": "Pending",
  "orderDisplayStatus": "Pending",
  "value": 0,
  "reference": "PROV-REF-000003",
  "playerId": "29df8b26-a2c8-4a45-9601-07fec4c4242d",
  "productId": "cd8ca7f8-550c-47cb-9563-e4d383aec965",
  "playerEmail": "user@user.com",
  "firstName": "John",
  "lastName": "Doe",
  "establishmentId": "522ef85f-7a5c-4ebb-b38d-46f40981be04",
  "establishmentName": "User Establishment",
  "establishmentImage": "/icon.png",
  "establishmentThumbnailUrl": "/logo.png",
  "transactionId": "6d5e3efe-f7ee-43ab-994e-372d80c56396",
  "address": null,
  "country": null,
  "postalCode": null,
  "city": null,
  "province": null,
  "date": "2025-04-11T12:42:39.469Z",
  "trackToken": "381tq7qzj5k34kdowsicw8",
  "trackUrl": "https://app.thepowerplugin.com/delivery?token=381tq7qzj5k34kdowsicw8&transactionId=6d5e3efe-f7ee-43ab-994e-372d80c56396"
}

Attribute	Type	Required
operationId	string(uuid)	Yes
orderType	string	Yes
orderStatus	string	Yes
orderDisplayStatus	string	Yes
value	number	Yes
reference	string	Yes
playerId	string(uuid)	Yes
productId	string(uuid)	Yes
playerEmail	string(email)	Yes
firstName	string	Yes
lastName	string	Yes
establishmentId	string(uuid)	Yes
establishmentName	string	Yes
establishmentImage	string	Yes
establishmentThumbnailUrl	string	Yes
transactionId	string(uuid)	Yes
address	string	Yes
country	string	Yes
postalCode	string	Yes
city	string	Yes
province	string	Yes
date	string(date-time)	Yes
trackToken	string	Yes
trackUrl	string(uri)	Yes

400

Invalid reservation payload.

500

Failed to reserve product.

PUT /orders/[playerId]/details/[transactionId]

Updates customer and billing details associated with an order transaction.

Endpoint

PUT/orders/{playerId}/details/{transactionId}

Request Body

{
  "email": "string",
  "address": "string",
  "country": "string",
  "postalCode": "string",
  "city": "string"
}

Attribute	Type	Required	Description
email	string	No	Customer email address
address	string	No	Street address
country	string	No	Country code or name
postalCode	string	No	Postal or ZIP code
city	string	No	City name

Parameters

Attribute	Description	Type	Location	Required
playerId	Unique identifier of the player	string	path	Yes
transactionId	Unique identifier of the transaction	string	path	Yes

Responses

200

Order details updated successfully

{
  "success": false,
  "message": "string"
}

Attribute	Type	Required	Description
success	boolean	No
message	string	No

400

Invalid request payload

404

Order or transaction not found

422

Validation error

500

Internal server error

DELETE /orders/[playerId]/reservation/[transactionId]

Cancels a previously created reservation by transaction ID. Frees up any reserved stock and removes pending entries.

Endpoint

DELETE/orders/{playerId}/reservation/{transactionId}

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes
transactionId		string	path	Yes

Responses

200

Reservation cancelled successfully.

400

Invalid cancellation request.

500

Server error while cancelling reservation.

POST /orders/[playerId]/send/[transactionId]

Captures delivery details for an existing reservation and keeps the order in the Reservation / Pending state. If shipping details were already captured, repeated calls are idempotent and do not decrement product stock again.

Endpoint

POST/orders/{playerId}/send/{transactionId}

Request Body

{
  "firstName": "string",
  "lastName": "string",
  "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "province": "string",
  "country": "string",
  "postalCode": "string",
  "email": "name@example.com"
}

Attribute	Type	Required	Description
firstName	string	No	Overrides the recipient first name stored on the reservation.
lastName	string	No	Overrides the recipient last name stored on the reservation.
addressLine1	string	No	Overrides the primary address line stored on the reservation.
addressLine2	string	No	Overrides the secondary address line stored on the reservation.
city	string	No	Overrides the destination city stored on the reservation.
province	string	No	Overrides the destination province stored on the reservation.
country	string	No	Overrides the destination country stored on the reservation.
postalCode	string	No	Overrides the postal code stored on the reservation.
email	string(email)	No	Overrides the recipient email stored on the reservation.

Parameters

Attribute	Description	Type	Location	Required
playerId	Player identifier that owns the reservation.	string	path	Yes
transactionId	Reservation transaction identifier.	string(uuid)	path	Yes

Responses

200

Reservation delivery details captured successfully.

{
  "operationId": "reservation-op-1",
  "transactionId": "11111111-1111-1111-1111-111111111111",
  "orderType": "Reservation",
  "orderStatus": "Pending",
  "orderDisplayStatus": "Pending",
  "playerId": "player-1",
  "productId": "product-1",
  "establishmentId": "est-1",
  "value": 100,
  "playerName": "John Doe",
  "playerEmail": "john@example.com",
  "address": {
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "Main St 1",
    "addressLine2": "Apt 3",
    "city": "Los Angeles",
    "province": "CA",
    "country": "US",
    "postalCode": "90210",
    "email": "john@example.com"
  },
  "deliveryDetailsCapturedAt": "2026-03-24T00:00:00.000Z"
}

Attribute	Type	Required
operationId	string	Yes
transactionId	string(uuid)	Yes
orderType	string	Yes
orderStatus	string	Yes
orderDisplayStatus	string	Yes
playerId	string	Yes
productId	string	Yes
establishmentId	string	Yes
value	number	Yes
playerName	string	No
playerEmail	string(email)	No
address	object	Yes
address.firstName	string	Yes
address.lastName	string	Yes
address.addressLine1	string	Yes
address.addressLine2	string	Yes
address.city	string	Yes
address.province	string	Yes
address.country	string	Yes
address.postalCode	string	Yes
address.email	string(email)	Yes
deliveryDetailsCapturedAt	string(date-time)	Yes

400

Invalid reservation state, or product stock cannot be decremented.

{
  "message": "Invalid operation or record status/type"
}

Attribute	Type	Required	Description
message	string	No

404

Transaction not found.

{
  "message": "Transaction not found"
}

Attribute	Type	Required	Description
message	string	No

422

Validation error for path or body fields.

{
  "example_key": [
    "string"
  ]
}

Attribute	Type	Required	Description
{key}	array<string>	No
{key}[]	string	No

500

Unexpected server error while updating product stock.

{
  "message": "Failed to update poduct stock"
}

Attribute	Type	Required	Description
message	string	No

POST /orders/[playerId]/track/[transactionId]

Registers a tracking number for a dispatched order. Used to update delivery status and notify the player.

Endpoint

POST/orders/{playerId}/track/{transactionId}

Request Body

{
  "trackingNumber": "string"
}

Attribute	Type	Required	Description
trackingNumber	string	Yes

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes
transactionId		string	path	Yes

Responses

200

Tracking number saved successfully.

400

Invalid tracking data.

500

Failed to register tracking number.

POST /orders/[playerId]/acquisition/[transactionId]

Finalizes the acquisition of a reserved product by marking it as completed. This may trigger reward attribution, stock deduction, or analytics updates.

Endpoint

POST/orders/{playerId}/acquisition/{transactionId}

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes
transactionId		string	path	Yes

Responses

200

Acquisition completed successfully.

400

Invalid acquisition request.

500

Server error during acquisition.

DELETE /orders/[playerId]/acquisition/[transactionId]

Cancels a product acquisition and optionally processes a refund. Useful in cases of duplicate redemptions, errors, or admin overrides.

Endpoint

DELETE/orders/{playerId}/acquisition/{transactionId}

Request Body

{
  "refund": false
}

Attribute	Type	Required	Description
refund	boolean	No

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes
transactionId		string	path	Yes

Responses

200

Acquisition cancelled successfully.

400

Invalid cancellation request.

500

Server error during cancellation.

POST /orders/list

Retrieves a paginated list of orders associated with the authenticated establishment, including search and filters.

Endpoint

POST/orders/list

Request Body

{
  "search": "string",
  "filters": {
    "status": [
      "string"
    ],
    "price": {
      "min": 0,
      "max": 0
    }
  },
  "pagination": {
    "page": 1,
    "limit": 25
  }
}

Attribute	Type	Required	Description
search	string	No	Search by transactionId and, for search strings with at least 3 characters, by product name through product search.
filters	object	No
filters.status	array<string>	No
filters.status[]	string	No
filters.price	object	No
filters.price.min	number	No
filters.price.max	number	No
pagination	object	No
pagination.page	integer	No
pagination.limit	integer	No

Responses

200

Orders retrieved successfully.

{
  "envelope": {
    "type": "string",
    "dataPath": "string"
  },
  "meta": {
    "pagination": {
      "total": 0,
      "page": 0,
      "limit": 0,
      "hasMore": false
    },
    "filters": {},
    "sort": {},
    "paginationControls": {}
  },
  "items": [
    {
      "operationId": "string",
      "playerId": "string",
      "establishmentId": "string",
      "orderStatus": "string",
      "orderType": "string",
      "date": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Attribute	Type	Required
envelope	object	No
envelope.type	string	No
envelope.dataPath	string	No
meta	object	No
meta.pagination	object	No
meta.pagination.total	integer	No
meta.pagination.page	integer	No
meta.pagination.limit	integer	No
meta.pagination.hasMore	boolean	No
meta.filters	object	No
meta.sort	object	No
meta.paginationControls	object	No
items	array<object>	No
items[]	object	No
items[].operationId	string	No
items[].playerId	string	No
items[].establishmentId	string	No
items[].orderStatus	string	No
items[].orderType	string	No
items[].date	string(date-time)	No

400

Invalid query or request format.

500

Server error while retrieving orders.

GET /players/[playerId]/orders

Retrieves a list of orders (acquisitions, redemptions, reservations) associated with the player.

Endpoint

GET/players/{playerId}/orders

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes

Responses

200

Orders retrieved successfully.

400

Invalid player ID.

500

Server error while fetching orders.

GET /players/[playerId]/orders/[transactionId]

Retrieves the details of a specific transaction by transaction ID for a player. Useful for auditing, reprocessing, or reviewing delivery history.

Endpoint

GET/players/{playerId}/orders/{transactionId}

Parameters

Attribute	Description	Type	Location	Required
playerId		string	path	Yes
transactionId		string	path	Yes

Responses

200

Transaction details retrieved.

500

Failed to retrieve transaction.

Products Players