> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/billing-api/wallet.md).
# Wallet
## Overview
The wallet API enables advertisers to manage digital wallets used for campaign budgeting and spend control. Each wallet is tied to a single currency and team, and supports features like daily budgets, and fund management.
Advertisers can maintain multiple wallets, each with its own credit balance and spend controls. With these APIs, you can:
* Manage wallet names
* View wallet IDs
* Access currency codes
* Set daily budgets
* Check current balances
* View available balances
* Control archive states
* Manage funds (Retailers only), and more
### Wallet fundamentals
#### Purpose
Wallets are essential tools for advertisers to manage, control, and report on campaign budgets. They allow granular tracking by region, product, or team, and support currency-specific budgeting and spend control.
Suppose your marketing team needs to run campaigns for three regions (US, EU, APAC), each with its own budget and currency. You create three wallets:
* **US Wallet (USD)**: $20,000, daily limit $2,000.
* **EU Wallet (EUR)**: €15,000, daily limit €1,500.
* **APAC Wallet (AUD)**: A$10,000, daily limit A$1,000.
Each campaign is linked to its region's wallet. If the US wallet runs low, only US campaigns pause. EU and APAC continue unaffected. You can report on spend, ROI, and pacing by wallet, and your finance team can reconcile each wallet separately.
{% hint style="info" %}
Advertisers can only use wallets on retailer catalogs that support the same currency.
{% endhint %}
#### Multiple wallets
Advertisers can create multiple wallets based on their operating model. Each campaign can be linked to only one wallet at a time, ensuring clear budget separation and spend tracking. You are free to use the default wallet if you do not wish to create multiple wallets.
#### Budget organization across wallets
Wallets help companies manage their advertising budgets by organizing funds based on currency and purpose. For example, large organizations can create separate wallets for different departments or campaigns. This setup allows each group to control its own daily spending without impacting others.
Each wallet maintains a credit balance in its designated currency, making it easier to manage budgets across multiple currencies. Advertisers can create multiple wallets, each with its own credit balance and unique wallet ID. This ID is used to identify and manage wallets individually.
{% hint style="info" %}
You need sufficient funds in your wallet to run a campaign. Once the wallet reaches its set budget, the ad stops running.
{% endhint %}
Since each campaign can be linked to only one wallet at a time, managing wallet balances effectively is crucial for uninterrupted campaign delivery.
#### Currency compatibility with catalogs
Some wallet features such as creating or editing wallets may not be available to all advertisers, depending on the retailer’s configuration. If a retailer has restrictions, you’ll see relevant error messages, and certain wallet-related functions may be hidden in the UI.
When creating a campaign and selecting a catalog, each catalog is associated with a specific currency. You must choose a wallet that matches the catalog's currency. For example, if your catalog uses AUD (Australian Dollar), you cannot select a wallet in GBP (British Pound). The system will prevent you from selecting a mismatched currency during campaign creation.
### Wallet features
Wallets help you manage budgets and spending across campaigns, including:
* **Multi-wallet support**: Enables budget separation by team, campaign, or department.
* **Currency-specific wallets**: Operates in a single currency.
* **Archived wallets**: Retains history without affecting active campaigns.
### Wallet elements
Each wallet includes the following key elements:
| Name | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Wallet name | The name assigned to the wallet. |
| Wallet ID | A unique identifier used to charge the correct wallet for a campaign. |
| Currency | The currency in which the wallet operates. |
| Current balance | The wallet's balance excluding any credit limit. |
| Available balance | The total spendable amount, including the credit limit. |
| Credit limit | An overspend allowance that resets monthly.
Note: This is a legacy feature and is not supported by most retailers.
|
| Archived state | Indicates that the wallet is no longer active but retained for records. |
You can view your team's wallets in the \*\*Wallets \*\*section. Depending on your retailer configuration, you may have access to view or modify specific wallet settings.
#### Example
Company A plans to allocate its advertising budget across three product types: $10,000 for Product A, $5,000 for Product B, and $1,200 for Product C. To manage this, the company creates three separate wallets, one for each product type with the corresponding amounts.
When setting up campaigns, each campaign is linked to the wallet assigned to its respective product. This setup allows the team to control and monitor the advertising spend for each product type independently, ensuring that budgets are used as intended.
#### What is an External ID?
An **external ID** is an optional field where you can store custom reference numbers like a purchase order, Salesforce ID, or Placement IO number. It helps partners track and link the wallet to their own systems.
> **Note:** This field is visible only if your retailer has enabled the feature flag.
### Budget limit and pacing
To help advertisers manage their daily ad spend effectively, wallets support the following controls:
#### Daily limit / Daily spend
The maximum amount a wallet is allowed to spend in a single day. This cap ensures that campaigns do not exceed a predefined daily budget.
#### Budget pacing
If the full daily limit is not spent on a given day, the unspent amount rolls over to the next day. This allows for flexible pacing of the budget across multiple days.
#### Remaining daily limit
The portion of the daily limit that remains unspent from the previous day. This amount is added to the next day's daily limit, enabling cumulative spending flexibility.
> **Note:** The availability of daily budget limits is subject to the retailer enabling the feature flag.
### Available endpoints
| Endpoint | Description |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Create wallet](/retail-media-interface/partner/billing-api/wallet/createwallet.md) | Set up a new wallet with a namespace, team, name, currency, daily budget, and optional external ID. |
| [Update wallet](/retail-media-interface/partner/billing-api/wallet/updatewallet-1.md) | Modify wallet name, currency, daily budget, credit limit, or external ID. |
| [Retrieve wallet by ID](/retail-media-interface/partner/billing-api/wallet/getwallet-1.md) | Fetch wallet details using its unique identifier. |
| [List all wallets](/retail-media-interface/partner/billing-api/wallet/listwallets.md) | Get a list of all wallets associated with your team. |
| [Get balance of specific wallet](/retail-media-interface/partner/billing-api/wallet/getwalletbalance.md) | Check current and available balances, using its unique identifier. |
| [Manage funds to specific wallet](/retail-media-interface/partner/billing-api/wallet/managefunds.md) | Add funds to a wallet to increase its available balance for campaign spending. |
### Wallet API field definitions
The following are key wallet fields commonly used in API requests and responses:
| Field | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| walletId | Unique identifier for the wallet. |
| currency | Currency code (e.g., USD, EUR). |
| creditLimit | Monthly overspend allowance.
Note: This is a legacy feature and is not supported by most retailers.
|
| dailyBudget | Daily spend cap. |
| availableBalance | Spendable amount including credit. |
| currentBalance | Actual wallet balance excluding credit. |
| externalId | Optional field for PO numbers, Salesforce IDs, etc. |
| archived | Boolean flag indicating if the wallet is archived. |
For common questions and troubleshooting, see [Frequently asked questions](/retail-media-interface/partner/partner-api-overview/frequently-asked-questions.md#wallet).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.citrusad.com/retail-media-interface/partner/billing-api/wallet.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.