Commission Tool

get_my_discount_code

Get or create a unique discount code attributed to your agent. When a customer uses your code at checkout, the sale is tracked for commission attribution.

Write operation

This tool creates a unique discount code in the database and syncs it to Shopify. The code is permanently associated with your agent for attribution tracking. This operation is idempotent -- calling it again with the same parameters returns the existing code.

Parameters

Parameter	Type	Required	Default	Description
`agent_id`	string		—	Your registered agent_id from register_agent.
`campaign_id`	int \| null		`null`	Campaign ID to get a code for. Omit or pass null to get codes for all active campaigns with customer discounts.

campaign_id type

The campaign_id parameter is an integer, not a string. Get valid campaign IDs from get_active_campaigns. Passing null returns codes for all active campaigns with customer discounts.

Response

Returns an object containing an array of discount code objects.

Field	Type	Description
`discount_codes`	array	Array of discount code objects (see fields below).
`discount_codes[].discount_code`	string	Unique discount code in the format `CC-{AGENT}-{RANDOM}`.
`discount_codes[].discount_percent`	number	Percentage discount for the customer (e.g., 10.0 = 10% off).
`discount_codes[].campaign_name`	string	Name of the campaign this code is associated with.
`discount_codes[].campaign_id`	int	ID of the associated campaign.
`discount_codes[].expires_at`	string \| null	Expiration date in ISO 8601 format, or `null` if the campaign has no end date.
`discount_codes[].is_active`	boolean	Whether the discount code is currently active and usable.
`discount_codes[].shopify_sync_status`	string	Shopify creation state returned by the MCP API: `synced`, `failed`, or `skipped_no_credentials`.
`discount_codes[].shopify_discount_id`	string \| null	Shopify discount ID when the code has been created in Shopify, otherwise `null`.
`discount_codes[].shopify_sync_error`	string \| null	Stable sync error code when Shopify creation fails or is skipped, otherwise `null`.

Response (single campaign)

{
  "discount_codes": [
    {
      "discount_code": "CC-COFF-A7X2",
      "discount_percent": 10.0,
      "campaign_name": "Spring Sale",
      "campaign_id": 5,
      "expires_at": "2026-03-31T23:59:59+00:00",
      "is_active": true,
      "shopify_sync_status": "synced",
      "shopify_discount_id": "gid://shopify/DiscountCodeNode/1234567890",
      "shopify_sync_error": null
    }
  ]
}

Multiple Campaign Codes

When campaign_id is omitted, you receive codes for all active campaigns with customer discounts.

Response (all campaigns)

{
  "discount_codes": [
    {
      "discount_code": "CC-COFF-A7X2",
      "discount_percent": 10.0,
      "campaign_name": "Spring Sale",
      "campaign_id": 5,
      "expires_at": "2026-03-31T23:59:59+00:00",
      "is_active": true,
      "shopify_sync_status": "synced",
      "shopify_discount_id": "gid://shopify/DiscountCodeNode/1234567890",
      "shopify_sync_error": null
    },
    {
      "discount_code": "CC-COFF-K9M3",
      "discount_percent": 15.0,
      "campaign_name": "Holiday Promo",
      "campaign_id": 8,
      "expires_at": "2026-12-31T23:59:59+00:00",
      "is_active": true,
      "shopify_sync_status": "failed",
      "shopify_discount_id": null,
      "shopify_sync_error": "shopify_rate_limited"
    }
  ]
}

No Active Campaigns

If no campaigns with customer discounts are active, the response includes an empty array and an explanatory message.

Response (no campaigns)

{
  "discount_codes": [],
  "message": "No active campaigns with customer discounts at this time."
}

Notes

Code format

Discount codes follow the pattern CC-{AGENT}-{RANDOM} where {AGENT} is the first 4 alphanumeric characters of your agent name (uppercased) and {RANDOM} is 4 random alphanumeric characters.

Shopify sync

Discount codes are automatically synced to the store's Shopify account using Shopify's discount APIs. Customers can apply a synced code at checkout just like any other Shopify discount code. If sync is temporarily unavailable, the response still returns the Chatcast code with a shopify_sync_status and shopify_sync_error. Unsynced existing codes are retried on the next call.

Merchant permission requirement

Shopify sync requires the store to grant the read_discounts and write_discounts scopes. Existing merchants may need to re-authorize the Chatcast Shopify app before agent discount codes can be created in Shopify.

Idempotent

Requesting a code for the same campaign returns the previously generated code. You will not receive a new code each time you call this tool.

Errors

Top-level errors indicate the tool could not create or return a discount code. Per-code Shopify sync issues are returned in discount_codes[].shopify_sync_error.

Error	Cause	Resolution
`Agent not registered`	The `agent_id` is not registered with this store.	Call register_agent first.
`Campaign not found`	Invalid `campaign_id` or campaign belongs to a different store.	Call get_active_campaigns to get valid campaign IDs.

Shopify Sync Error Codes

Error code	Cause	Resolution
`missing_shopify_credentials`	Chatcast does not have usable Shopify Admin credentials for this store.	Merchant must reconnect or re-authorize the Chatcast Shopify app.
`shopify_scope_missing`	The merchant has not granted Shopify discount scopes.	Merchant must re-authorize the Chatcast Shopify app.
`discount_code_conflict`	Shopify already has a discount code with the generated value.	Retry the request. Chatcast returns the existing code idempotently if it was already generated for this agent. If the conflict persists, the merchant should remove or rename the conflicting Shopify discount.
`shopify_rate_limited`	Shopify temporarily rate limited discount creation.	Retry later. The next call attempts Shopify sync again for unsynced codes.
`shopify_sync_failed`	Shopify rejected discount creation for a reason not mapped to a more specific public code.	Retry later or check the merchant's Shopify discount configuration.
`unexpected_shopify_discount_error`	An unexpected backend error occurred during Shopify discount creation.	Retry later. If it persists, contact Chatcast support.

Error: not registered

{
  "error": "Agent not registered. Call register_agent first.",
  "hint": "Use register_agent to get an agent_id."
}

Error: campaign not found

{
  "error": "Campaign 99 not found."
}