Fill cart by cart ID with items

Xsolla Developers

Fill cart by cart ID with itemsServer-side

put/v2/admin/project/{project_id}/cart/{cart_id}/fill

Fills the cart by cart ID with items. If the cart already has an item with the same SKU, the existing item will be replaced by the passed value.

SecuritybasicAuth

Request

path Parameters

project_id required	integer Project ID. You can find this parameter in your Publisher Account next to the name of the project. Example: 44056
cart_id required	string Cart ID. Example: custom_id

query Parameters

locale

string

Default: "en"

Response language. Two-letter lowercase language code per ISO 639-1.

header Parameters

x-user-for	string User identifier can be transferred by using the Xsolla Login User JWT or the Pay Station access token. Example: ACCESS_TOKEN/LOGIN_JWT
x-user-id	string <= 32 characters You can use your own user ID when selling a cart with games. Example: UNIQUE_ID

Request Body schema: application/json

required

Array of objects non-empty

Array (non-empty)

sku required	string non-empty Unique item ID. The SKU may contain only lowercase and uppercase Latin alphanumeric characters, periods, dashes, and underscores.
quantity required	number >= 1 Quantity of the item.

country

string = 2 characters

Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla.
Example: country=US

currency

string = 3 characters

The item price currency displayed in the cart. Three-letter code per ISO 4217. Check the documentation for detailed information about currencies supported by Xsolla.

Responses

200

The cart with items was successfully returned.

401

Basic authentication not passed or wrong. Make sure you used basic authentication or correct credentials.

404

The user was not found. Make sure the x-user-for or x-user-id token is correct.

422

Invalid cart. Check that cart exists, not empty, and all items in it are not free.

Request samples

application/json

{"currency": "USD",
"items": [{"sku": "com.xsolla.cup01",
"quantity": 2
},
{"sku": "com.xsolla.t-shirt01",
"quantity": 1
},
{"sku": "com.xsolla.cup01",
"quantity": 1
},
{"sku": "com.xsolla.hat01",
"quantity": 1
}
]
}

Response samples

application/json

{"cart_id": "cart_id",
"is_free": false,
"items": [{"attributes": [ ],
"description": "The cup of tea",
"groups": [{"external_id": "cups",
"name": "Cups"
}
],
"image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png",
"is_free": false,
"is_bonus": false,
"name": "Cup",
"price": {"amount": "5.99",
"amount_without_discount": "5.99",
"currency": "USD"
},
"quantity": 2,
"sku": "com.xsolla.cup01",
"type": "physical_good",
"virtual_prices": [ ],
"promotions": [ ],
"can_be_bought": true,
"vp_rewards": [{"item_id": 175232,
"sku": "com.xsolla.value_point_1",
"amount": 130,
"name": "Value point",
"image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg"
},
{"item_id": 186321,
"sku": "com.xsolla.clan_value_point_1",
"amount": 50,
"name": "Clan Reward VP 1",
"image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg",
"is_clan": true
}
],
"limits": {"per_user": {"available": 3,
"recurrent_schedule": {"interval_type": "weekly",
"reset_next_date": 1746057600
},
"total": 5
}
},
"periods": [{"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
]
},
{"attributes": [ ],
"description": "Wonderful white T-shirt",
"groups": [ ],
"image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png",
"is_free": false,
"is_bonus": false,
"name": "White T-shirt",
"price": {"amount": "3.99",
"amount_without_discount": "4.99",
"currency": "USD"
},
"quantity": 1,
"sku": "com.xsolla.t-shirt01",
"type": "physical_good",
"virtual_prices": [ ],
"promotions": [{"name": "Bonus promotion",
"date_start": "2020-04-15T16:16:00+03:00",
"date_end": "2026-04-15T16:16:00+03:00",
"discount": {"percent": "50.00"
},
"bonus": [{"quantity": 1,
"name": "Xsolla Minigun",
"image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png",
"sku": "com.xsolla.minigun_1",
"type": "virtual_good"
}
]
}
],
"can_be_bought": true,
"vp_rewards": [{"item_id": 175232,
"sku": "com.xsolla.value_point_1",
"amount": 130,
"name": "Value point",
"image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg"
},
{"item_id": 186321,
"sku": "com.xsolla.clan_value_point_1",
"amount": 50,
"name": "Clan Reward VP 1",
"image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg",
"is_clan": true
}
],
"limits": {"per_user": {"available": 3,
"recurrent_schedule": {"interval_type": "weekly",
"reset_next_date": 1746057600
},
"total": 5
}
},
"periods": [{"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
]
},
{"attributes": [ ],
"description": "Wonderful white T-shirt",
"groups": [{"external_id": "clothes",
"name": "Clothes"
}
],
"image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png",
"is_free": true,
"is_bonus": false,
"name": "Cat's cup",
"price": null,
"quantity": 1,
"sku": "com.xsolla.cup01",
"type": "physical_good",
"virtual_prices": [ ],
"promotions": [ ],
"can_be_bought": true,
"vp_rewards": [{"item_id": 175232,
"sku": "com.xsolla.value_point_1",
"amount": 130,
"name": "Value point",
"image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg"
},
{"item_id": 186321,
"sku": "com.xsolla.clan_value_point_1",
"amount": 50,
"name": "Clan Reward VP 1",
"image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg",
"is_clan": true
}
],
"limits": {"per_user": {"available": 3,
"recurrent_schedule": {"interval_type": "weekly",
"reset_next_date": 1746057600
},
"total": 5
}
},
"periods": [{"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
]
}
],
"warnings": [{"sku": "com.xsolla.hat01",
"quantity": 1,
"errorCode": 4001,
"errorMessage": "[0401-4001]: Item with Project Id = 44056 and Sku = hut01 not found"
}
],
"price": {"amount": "15.97",
"amount_without_discount": "22.96",
"currency": "USD"
},
"promotions": [{"name": "Bonus promotion",
"date_start": "2020-04-15T16:16:00+03:00",
"date_end": "2026-04-15T16:16:00+03:00",
"discount": {"percent": "50.00"
},
"bonus": [{"quantity": 1,
"name": "Xsolla Minigun",
"image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png",
"sku": "com.xsolla.minigun_1",
"type": "virtual_good"
}
]
}
]
}