Check the stamp balance of your account or your sub-accounts, and add or remove stamps for your customers from your code.
View SDKs✓Before you start
- 1Get a Bearer Token for your dealer account using your SW username and password. We recommend using an infinite (non-expiring) token. All operations require it in the
Authorizationheader. - 2Find the sub-account’s
idUserwith Users API V2 › Query. - 3Before using Remove, check its
stampsBalancewith Query › By ID: you can’t remove more stamps than it has.
💡 Important: My balance returns the stamps of the account that owns the token. By ID, Add, and Remove operate on your sub-accounts.
URLs
Select your active environment. The copy buttons and the code examples below are built with the base URL you choose here.
🛠️ Sandbox:
https://api.test.sw.com.mx
🚀 Production:
https://api.sw.com.mx
🔗 Endpoint
Three actions on the stamp balance. Pick one and its full reference is built below: endpoint, headers, parameters, example, and response.
Adds a number of stamps to one of your sub-accounts. The response returns its new balance.
POST/management/v2/api/dealers/users/{userId}/stamps
Property
Usage
Description
Authorization
REQUIRED
Bearer {token} — your dealer account token.
Content-Type
REQUIRED
application/json — the body is sent as JSON.
Property
Type
Usage
Description
userId
guid
REQUIRED
ID of the sub-account the stamps will be added to. Get it with Users API V2 › Query (idUser).
Property
Type
Usage
Description
stamps
int
REQUIRED
Number of stamps to add.
comment
string
OPTIONAL
Comment attached to the transaction.
Checks the available, used, and assigned stamps of the account linked to the token.
GET/management/v2/api/users/balance
Checks the available stamps of one of your sub-accounts, filtered by its ID.
GET/management/v2/api/dealers/balance/users/{idUser}
Property
Type
Usage
Description
idUser
guid
REQUIRED
ID of the sub-account to query. Get it with Users API V2 › Query (idUser).
Removes a number of stamps from one of your sub-accounts. The response returns its new balance.
DELETE/management/v2/api/dealers/users/{userId}/stamps
🚨 Important: you can’t remove more stamps than the sub-account has available. Check its balance first with Query › By ID. Removed stamps go back to the parent account.
Property
Usage
Description
Authorization
REQUIRED
Bearer {token} — your dealer account token.
Content-Type
REQUIRED
application/json — the body is sent as JSON.
Property
Type
Usage
Description
userId
guid
REQUIRED
ID of the sub-account the stamps will be removed from. Get it with Users API V2 › Query (idUser).
Property
Type
Usage
Description
stamps
int
REQUIRED
Number of stamps to remove.
comment
string
OPTIONAL
Comment attached to the transaction.
Request Example
💡 Note: These examples are based on the SW SDKs, but you can call the REST API directly from any language you prefer.
Response
Property
Type
Description
status
string
Response status: "success" or "error".
data
int | null
Sub-account’s total stamps after the top-up.
Cause: The userId doesn’t exist or doesn’t belong to your dealer account.
Solution: Confirm the idUser with Users API V2 › Query, using the dealer account token.
Property
Type
Description
status
string
Response status: "success" or "error".
message
string
Only present in error responses. Describes the cause of the failure.
Property
Type
Description
status
string
Response status: "success" or "error".
data
object | null
Account balance.
data.stampsBalance
int
Available stamps.
data.stampsUsed
int
Stamps used.
data.stampsAssigned
int
Total stamps assigned.
data.isUnlimited
boolean
Indicates whether the account has unlimited stamps.
data.expirationDate
string | null
Balance expiration date, if applicable.
data.lastTransaction
object | null
Latest stamp transaction. See fields below.
Cause: The token doesn’t belong to a valid account.
Solution: Generate a new token with Authentication V2 and repeat the query.
Property
Type
Description
status
string
Response status: "success" or "error".
message
string
Only present in error responses. Describes the cause of the failure.
Property
Type
Description
status
string
Response status: "success" or "error".
data
object | null
Account balance.
data.stampsBalance
int
Available stamps.
data.stampsUsed
int
Stamps used.
data.stampsAssigned
int
Total stamps assigned.
data.isUnlimited
boolean
Indicates whether the account has unlimited stamps.
data.expirationDate
string | null
Balance expiration date, if applicable.
data.lastTransaction
object | null
Latest stamp transaction. See fields below.
Cause: The sub-account doesn’t belong to the token’s dealer account.
Solution: Verify the idUser with Users API V2 › Query, using the parent account token.
Property
Type
Description
status
string
Response status: "success" or "error".
message
string
Only present in error responses. Describes the cause of the failure.
Property
Type
Description
status
string
Response status: "success" or "error".
data
int | null
Sub-account’s total stamps after the removal.
Cause: The userId doesn’t exist or doesn’t belong to your dealer account.
Solution: Confirm the idUser with Users API V2 › Query, using the dealer account token.
Property
Type
Description
status
string
Response status: "success" or "error".
message
string
Only present in error responses. Describes the cause of the failure.
Cause: The amount to remove is greater than the sub-account’s available balance.
Solution: Check its stampsBalance with Query › By ID and send an equal or smaller amount.
Property
Type
Description
status
string
Response status: "success" or "error".
message
string
Only present in error responses. Describes the cause of the failure.
📋 data.lastTransaction fields
The object has 10 fields describing the account’s latest stamp transaction, whether a top-up or a removal. Click View all 10 fields to expand the table.
Field
Type
Description
folio
int
Sequential transaction folio.
idUser
guid
ID of the account that made the transaction.
idUserReceiver
guid
ID of the account that received the transaction.
nameReceiver
string
Receiving account: email, RFC, and name.
stampsIn
int | null
Stamps added. null if it was a removal.
stampsOut
int | null
Stamps removed. null if it was a top-up.
stampsCurrent
int
Account balance after the transaction.
comment
string | null
Comment entered with the transaction.
date
string
Transaction date and time.
isEmailSent
boolean
Indicates whether an email notification was sent.