Skip to main content
The promotional codes API lets you create discount codes that drivers can apply to their charging sessions. Codes support both percentage-based and fixed-amount discounts, with optional usage limits and expiry dates. This section also covers the user types API, which lets you segment drivers into groups for use with billing rules.

​
Create a promotional code

POST /api/v1/billing/promotional-codes
​
code
string
required
The code string drivers will enter (e.g. SUMMER25). Must be unique within your organisation. Uppercase letters and numbers only, 4–20 characters.
​
discount_type
string
required
How the discount is calculated. Accepted values: percent (percentage off the total), fixed (fixed amount off the total).
​
discount_value
number
required
The discount amount. For percent, this is the percentage (e.g. 25 for 25% off). For fixed, this is the amount in your default currency.
​
currency
string
ISO 4217 currency code. Required when discount_type is fixed.
​
max_uses
number
Maximum number of times this code can be redeemed across all users. Leave unset for unlimited uses.
​
max_uses_per_user
number
Maximum number of times a single user can redeem this code. Leave unset for unlimited.
​
expires_at
string
ISO 8601 date/time after which the code can no longer be applied. Leave unset for no expiry.
​
description
string
Internal description for the code — not shown to drivers.
curl -X POST "https://api.dynamo-csms.com/api/v1/billing/promotional-codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER25",
    "discount_type": "percent",
    "discount_value": 25,
    "max_uses": 500,
    "max_uses_per_user": 1,
    "expires_at": "2024-08-31T23:59:59Z",
    "description": "Summer 2024 promotion — 25% off one session"
  }'

{
  "code_id": "promo_7XNBQ",
  "code": "SUMMER25",
  "discount_type": "percent",
  "discount_value": 25,
  "currency": null,
  "max_uses": 500,
  "max_uses_per_user": 1,
  "uses_count": 0,
  "expires_at": "2024-08-31T23:59:59Z",
  "description": "Summer 2024 promotion — 25% off one session",
  "active": true,
  "created_at": "2024-06-01T10:00:00Z"
}
​
code_id
string
Unique identifier for the promotional code.
​
code
string
The code string.
​
uses_count
number
Number of times this code has been successfully redeemed.
​
active
boolean
Whether the code is currently redeemable. Set to false automatically when max_uses is reached or expires_at passes.

​
List promotional codes

GET /api/v1/billing/promotional-codes Returns all promotional codes in your organisation.
​
active
boolean
Filter by active status.
​
discount_type
string
Filter by discount type: percent or fixed.
​
limit
number
default:"50"
Maximum number of codes to return.
​
offset
number
default:"0"
Pagination offset.
curl "https://api.dynamo-csms.com/api/v1/billing/promotional-codes?active=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "codes": [
    {
      "code_id": "promo_7XNBQ",
      "code": "SUMMER25",
      "discount_type": "percent",
      "discount_value": 25,
      "uses_count": 47,
      "max_uses": 500,
      "expires_at": "2024-08-31T23:59:59Z",
      "active": true
    }
  ],
  "total": 1
}

​
Get a promotional code

GET /api/v1/billing/promotional-codes/{code_id}
​
code_id
string
required
The unique identifier of the promotional code.
curl "https://api.dynamo-csms.com/api/v1/billing/promotional-codes/promo_7XNBQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "code_id": "promo_7XNBQ",
  "code": "SUMMER25",
  "discount_type": "percent",
  "discount_value": 25,
  "currency": null,
  "max_uses": 500,
  "max_uses_per_user": 1,
  "uses_count": 47,
  "expires_at": "2024-08-31T23:59:59Z",
  "description": "Summer 2024 promotion — 25% off one session",
  "active": true,
  "created_at": "2024-06-01T10:00:00Z"
}

​
Apply a promotional code to a session

POST /api/v1/billing/promotional-codes/sessions/{session_id}/apply-code Applies a promotional code to a completed session. The discount is calculated and recorded against the session. This endpoint can be called by a driver application or by an operator on behalf of a driver.
Codes can only be applied to sessions with status completed. Active sessions cannot have a code applied until the session ends.
​
session_id
string
required
The billing session to apply the code to.
​
code
string
required
The promotional code string to apply.
curl -X POST "https://api.dynamo-csms.com/api/v1/billing/promotional-codes/sessions/sess_7MNBPX/apply-code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "SUMMER25"}'

{
  "session_id": "sess_7MNBPX",
  "code": "SUMMER25",
  "code_id": "promo_7XNBQ",
  "discount_type": "percent",
  "discount_value": 25,
  "original_cost": 5.52,
  "discount_amount": 1.38,
  "final_cost": 4.14,
  "currency": "GBP",
  "applied_at": "2024-06-05T09:45:00Z"
}
​
original_cost
number
Session total before the code was applied.
​
discount_amount
number
Amount discounted from the session.
​
final_cost
number
Session total after the discount.

​
Get promotional code usage stats

GET /api/v1/billing/promotional-codes/{code_id}/usage Returns detailed usage statistics for a promotional code, including a breakdown of redemptions over time.
​
code_id
string
required
The unique identifier of the promotional code.
​
from
string
ISO 8601 start date/time to filter usage from.
​
to
string
ISO 8601 end date/time to filter usage to.
curl "https://api.dynamo-csms.com/api/v1/billing/promotional-codes/promo_7XNBQ/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "code_id": "promo_7XNBQ",
  "code": "SUMMER25",
  "total_redemptions": 47,
  "unique_users": 47,
  "total_discount_given": 64.86,
  "currency": "GBP",
  "redemptions_by_day": [
    { "date": "2024-06-01", "count": 5, "discount_total": 6.90 },
    { "date": "2024-06-02", "count": 8, "discount_total": 11.04 },
    { "date": "2024-06-03", "count": 12, "discount_total": 16.56 }
  ]
}
​
total_redemptions
number
Total number of times the code has been applied.
​
unique_users
number
Number of distinct users who redeemed the code.
​
total_discount_given
number
Total value discounted across all redemptions.
​
redemptions_by_day
object[]
Daily redemption counts and discount totals for the requested period.

​
User types

User types let you segment drivers into groups so billing rules can target them specifically. For example, you might create types like staff, fleet, and public and then write rules that grant free sessions to staff drivers.

​
Create a user type

POST /api/v1/billing/user-types
​
name
string
required
Unique name for the user type (e.g. staff, fleet-customer, vip).
​
description
string
Optional description of who belongs to this type.
curl -X POST "https://api.dynamo-csms.com/api/v1/billing/user-types" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staff",
    "description": "Company employees eligible for free charging"
  }'

{
  "user_type_id": "utype_3KLMX",
  "name": "staff",
  "description": "Company employees eligible for free charging",
  "created_at": "2024-06-01T09:00:00Z"
}

​
List user types

GET /api/v1/billing/user-types Returns all user types in your organisation. 
curl "https://api.dynamo-csms.com/api/v1/billing/user-types" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "user_types": [
    {
      "user_type_id": "utype_3KLMX",
      "name": "staff",
      "description": "Company employees eligible for free charging",
      "user_count": 18,
      "created_at": "2024-06-01T09:00:00Z"
    },
    {
      "user_type_id": "utype_9XVBQ",
      "name": "fleet",
      "description": "Fleet account drivers",
      "user_count": 64,
      "created_at": "2024-05-15T10:30:00Z"
    }
  ]
}

​
Assign a user type to a driver

PUT /api/v1/billing/user-types/users/{user_id}/user-type Sets the user type for a specific driver. Replaces any previously assigned type.
​
user_id
string
required
The user to assign the type to.
​
user_type_id
string
required
The user type to assign.
curl -X PUT "https://api.dynamo-csms.com/api/v1/billing/user-types/users/usr_9PLKJ/user-type" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_type_id": "utype_3KLMX"}'

{
  "user_id": "usr_9PLKJ",
  "user_type_id": "utype_3KLMX",
  "user_type_name": "staff",
  "assigned_at": "2024-06-15T11:00:00Z"
}