RequestId format
RequestId must be a GUID and it must be unique per client.
POST
Place Order
Create a Bamboo order that charges an active account balance and returns the request identifier used to track fulfillment.
POST
/api/integration/v1.0/orders/checkoutFollow this flow to place your first order
View all steps1
Get catalog
Discover available products
2
Get accounts
Retrieve your accounts
3
Place order
Create an order for your customer
4
Get order
Check order status
5
Notification
Receive webhook updates
Place Order creates an order immediately. Bamboo does not create drafts or unprocessed order shells through this endpoint.
A successful response returns the submitted RequestId. Use that value with Get Order to retrieve the full order details and purchased card data.
This endpoint requires Basic Auth using your API credentials.
Request body
Send a JSON payload containing a unique RequestId, the account to charge, and the list of products to purchase.
{
"RequestId": "97018cf7-98f5-40fc-a142-711d43a72e17",
"AccountId": 555,
"Products": [
{
"ProductId": 439685,
"Quantity": 2,
"Value": 10
}
]
}| Field | Type | Description |
|---|---|---|
RequestId | string | Unique client-side GUID used to identify the order. |
AccountId | number | Active Bamboo account ID returned by Get Accounts. |
Products | array | Collection of products to purchase in the same order. |
ProductId | number | Product identifier returned by Get catalog. |
Quantity | number | Number of cards to purchase for the product. |
Value | number | Face value to issue for the selected product. |
Request remarks
Validate these inputs before sending the order to Bamboo.
Active account
AccountId must reference an active Bamboo account returned by Get Accounts.
Environment matching
Sandbox AccountId values and live AccountId values are different and must not be mixed.
Catalog validation
ProductId must exist in your catalog and be available to your authenticated client.
Denomination validation
Value must fall between MinFaceValue and MaxFaceValue for the selected product.
Response and validation errors
A successful response returns the request identifier. Validation and order acceptance failures return a 400 error with a Bamboo reason code.
Successful response
| Field | Type | Description |
|---|---|---|
requestId | string | The GUID returned as a JSON string. Use it with Get Order. |
400 error reasons
| Reason | Meaning |
|---|---|
WrongAccount | The supplied AccountId is invalid for the authenticated client or current environment. |
InsufficientBalance | The selected account does not have enough balance to settle the order. |
InvalidProductIds | One or more ProductId values are missing or invalid. |
InvalidProduct | The product configuration is invalid or cannot be ordered. |
InvalidDenomination | The requested Value is outside the supported MinFaceValue and MaxFaceValue range. |
NoProducts | The request body does not contain any products. |
OrderAlreadyExists | The submitted RequestId has already been used for another order. |
ClientCatalogNotExist | No catalog is available for the authenticated client. |
OrderNotFound | The referenced order could not be found. |
CardsLimitExceeded | The requested order exceeds the 500-card maximum. |
ProductIsOutOfStock | The selected product is currently unavailable. |
ClientPriceInvalid | The stored client price no longer matches Bamboo pricing rules. |
UserNotEnabled | The authenticated user is not enabled to place orders. |
Examples
Full request and response examples for this endpoint.
Example request
Use this full request as the primary reference for client-side implementation.
# Generate token: echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64
curl --location 'https://api.bamboocardportal.com/api/integration/v1.0/orders/checkout' \
--header 'Authorization: Basic YOUR_BASE64_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"RequestId": "97018cf7-98f5-40fc-a142-711d43a72e17",
"AccountId": 555,
"Products": [
{
"ProductId": 439685,
"Quantity": 2,
"Value": 10
}
]
}'Example response
Use this sample payload to validate parsing, field mapping, and downstream handling.
200 OK
"71ac2817-e51a-438a-bb7b-5ffdda23603c"Ordering and pricing behavior
These rules affect how Bamboo accepts, prices, and processes order requests.
Account source
AccountId must come from the Get Accounts endpoint for the same client and environment.
Duplicate RequestId
Submitting the same RequestId again causes OrderAlreadyExists instead of creating a second order.
Immediate processing
Orders process immediately after Bamboo accepts the request. There is no draft or unprocessed order creation path.
Value meaning
Value represents the product face value, not the client settlement price.
Cross-currency example
If a EUR 10 product is settled from a USD account at an exchange rate of 1.0851, Bamboo charges USD 10.851 per card. Ordering quantity 10 results in a USD 108.51 charge.
Limits and safeguards
Throttle your ordering client and validate quantities to stay inside Bamboo operating limits.
Card limit per order
A single order can contain a maximum of 500 cards, and Products[].Quantity must respect that total limit.
Pacing between requests
Wait at least 500ms between consecutive Place Order calls.
Same-product burst limit
Do not submit more than 6 orders for the same product within 1 minute.
On this page
Try it out
Open the interactive API panel to test this endpoint with your own credentials.