What changed in the API.

Issue Points: timeouts, partner rejections and transaction status

A 504 now means the outcome is unknown and the same request should be resent; partner rejections come back as a 400 with the partner's text; transactions carry a status and failed ones are listed.

• Added

  504 Gateway Timeout on Issue Points. Cosmo holds the request for up to 30 seconds while the partner is called, so set your client timeout to 31 seconds or more. A 504, a dropped connection or no response means the outcome is unknown: do not reverse anything, resend the exact same request with the same referenceNumber until you get a definitive answer. A resend never issues points twice.

• Changed

  503 is a definitive failure, not a timeout: the transaction is recorded as FAILED, no points were issued, and the reference number is consumed. 500 is also definitive, and the reference number may be reused.

• Added

  Partner rejections on Issue Points. When the partner program refuses the credit (unknown, blocked or closed membership, for example) the 400 carries a second shape: errorCode, message, and data.partnerError with the partner's own error text. The reference number stays used.

• Added

  409 with errorCode TRANSACTION_FAILED when a reference number belongs to a failed transaction, alongside the existing CONFLICT for reuse with different transfer details.

• Added

  status on every transaction read, COMPLETED or FAILED. The transaction list now includes failed transactions, so filter on status rather than assuming every listed transaction succeeded. Point transactions are empty unless the status is COMPLETED.

• Changed

  On transaction reads, sourceValue is renamed localCurrencyValue, and the nested destination object (name, programId) is replaced by destinationProgramId.

• Changed

  Point transaction type is now BASE, PARTNER_CAMPAIGN or CLIENT_CAMPAIGN; it was BASE or CAMPAIGN.

• Deprecated

  partnerTransactionId on Issue Points responses. Reconcile on id and referenceNumber instead.

What isValid means for programs without a validation endpoint

For partner programs that offer no member-validation API, isValid reports that the submitted details pass the program's format rules, not that the member exists.

• Changed

  isValid is documented per partner: where the program exposes a validation endpoint it confirms membership; where it does not, it confirms only that the details satisfy the program's validation rules and says nothing about eligibility to receive points. The per-program rules are listed on the Partner Validation Support and Rules page.

Campaign funding fields, point-based limits and basePoints on Issue Points

Campaigns expose who funds the bonus, programs expose four point-based transfer limits, and Issue Points takes basePoints and bonusPoints instead of value and currency.

• Added

  fundedBonusPercentage and partnerFundedBonusPercentage on campaigns. The bonus to send is floor(basePoints × fundedBonusPercentage / 100); the total bonus is the sum of the two.

• Deprecated

  yourCostSharePercentage and extraPointsPercentage on campaigns, replaced by the two fields above.

• Added

  basePoints and optional bonusPoints on Issue Points. Send either basePoints (with bonusPoints where a campaign applies) or the older value and currency pair.

• Deprecated

  value and currency on Issue Points. Use basePoints.

• Added

  minAllowedPoints and maxAllowedPoints (set by you) and partnerMinAllowedPoints and partnerMaxAllowedPoints (set by the partner) on programs, all expressed in destination points. New 400 error codes MIN_SOURCE_NOT_REACHED, MAX_SOURCE_EXCEEDED, MIN_DESTINATION_NOT_REACHED and MAX_DESTINATION_EXCEEDED when a transfer falls outside them.

• Deprecated

  minAmountOfPoints, maxAmountOfPoints, minValue and maxValue on programs, replaced by the four limits above.

• Deprecated

  POST /transactions/preview. Compute the points from the program's limits and the campaign's percentages instead.

The new fields first landed on 23 September under interim names (sourceMinAllowedPoints, destinationMinAllowedPoints, yourFundedBonusPercentage) and were renamed the next day. Only the names above are supported.

The /auth endpoint and two deprecated program fields are removed

The legacy authentication endpoint is gone; use the OAuth 2.0 token endpoint. Two long-deprecated price fields left the programs response.

• Removed

  POST /auth, deprecated since before December 2025. Obtain tokens from POST /oauth2/token with the client-credentials grant.

• Removed

  pricePerPoint and currency on programs, deprecated since December 2025. Use pricePerPointInUsd, pricePerPointInLocalCurrency and localCurrency.

Multibrand credit and debit are de-duplicated on referenceNumber

Both endpoints require a unique referenceNumber, share one namespace, and return the original transaction on a replay.

• Changed

  referenceNumber is required and must be unique across your Multibrand transactions. Credit and debit share a single namespace, so a reference number used on one cannot be reused on the other. A reference number is never released.

• Added

  200 on a replay: the same referenceNumber with identical details returns the original transaction (sourceUserId, sourceProgramId, valueInSourceLocalCurrency, valueInUsd, localCurrency, status, createdAt, executionDate) and the user is not credited or debited again. Status is PENDING, MATURED or EXECUTED.

• Added

  409 with errorCode CONFLICT when the reference number was used with different details, or while the original request is still being processed.

logoDarkMode on profile, programs and campaigns

A dark-mode logo URL is returned next to logo wherever a logo is returned.

• Added

  logoDarkMode, the URL of the business or program logo for dark backgrounds, alongside the existing logo.

Issue Points is de-duplicated on referenceNumber

referenceNumber is required and unique; a retry with the same details returns the original transaction instead of creating a second one.

• Changed

  referenceNumber is required and must be unique across all your transactions. It is the de-duplication key for the endpoint.

• Added

  200 on a replay: the same referenceNumber with identical transfer details returns the original transaction (id, totalPoints, referenceNumber, date) and the partner is not credited again. A new transaction still returns 201.

• Added

  409 with errorCode CONFLICT when the reference number was already used with different transfer details, or while the original transaction is still pending.

Standard error responses across the API, and 201 on Issue Points

Every endpoint documents 403, the lookups document 404, list endpoints validate their query parameters, 400s carry an errorCode, and a new transaction returns 201.

• Changed

  Issue Points returns 201 Created for a new transaction. It returned 200 before. Clients that check for exactly 200 must accept 201.

• Added

  403 Forbidden on every authenticated endpoint; 404 on profile, transaction and program-connection lookups; 422 on list endpoints when a query parameter is missing or invalid; 500 and 503 on Issue Points.

• Added

  errorCode on 400 responses: BLOCKED_USER, DESTINATION_BLOCKED_USER, PARTNERSHIP_NOT_FOUND, INVALID_CURRENCY, PARTNER_CODE_REQUIRED, MIN_POINTS_NOT_REACHED, MAX_POINTS_EXCEEDED, MIN_VALUE_NOT_REACHED, MAX_VALUE_EXCEEDED and BAD_REQUEST.

• Changed

  Token endpoint errors follow OAuth 2.0: 400 with error invalid_request or unsupported_grant_type, and 401 for invalid client credentials. They were 401 and 422.

First and last name for the destination user

Optional destinationUserFirstName and destinationUserLastName, for programs that need the member's name.

• Added

  destinationUserFirstName and destinationUserLastName as optional request fields on Issue Points, preview, validate-member and Multibrand credit. Both are echoed in transaction responses.

partnerCode on programs and campaigns

Each program and campaign returns the partner code it belongs to.

• Added

  partnerCode on every program and campaign, so you can send it on Issue Points without a separate lookup.

Multibrand debit is a POST

The debit endpoint changed method from DELETE to POST.

• Changed

  POST /multibrand/debit replaces DELETE /multibrand/debit. The request body is unchanged.

Campaign status IDLE is renamed UPCOMING

The status filter and the campaign object use UPCOMING for campaigns that have not started.

• Changed

  Campaign status values are UPCOMING, RUNNING, STOPPED and EXPIRED. Filters and comparisons on IDLE must use UPCOMING.

Multibrand API published, and connection routes renamed

Nine Multibrand endpoints join the public reference, the connections routes move under program-connections, and the connection object is simplified.

• Added

  Public endpoints for Multibrand: programs, member validation, currencies, credit, the transaction list, debit, balance, pending points and monthly statistics.

• Changed

  /multibrand/multibrand-connections, its history and its delete route are renamed /multibrand/program-connections, /multibrand/program-connections/history and /multibrand/program-connections/{id}.

• Changed

  The program connection object is flattened: destinationUserId and destinationUserEmail sit at the top level, and connections is a list of percentage and destinationProgramId.

• Deprecated

  pricePerPoint and currency on programs. Use pricePerPointInUsd, pricePerPointInLocalCurrency and localCurrency. Removed in September 2026.

• Changed

  startDate and endDate on the campaigns list are optional.