> ## Documentation Index > Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt > Use this file to discover all available pages before exploring further. # Allocate rewards > Allocate rewards for a payment operation. ## OpenAPI ````yaml api-reference/payment-acceptance/payment-acceptance-api.yaml post /api/v1/rewards/allocate openapi: 3.1.1 info: title: Coinbase Commerce API description: API for processing payments on the PaymentEscrow smart contract protocol. version: v0.0.1 servers: - url: https://payments.coinbase.com security: [] tags: - name: Payments description: >- Endpoints focused on handling payment transactions. This includes operations for authorizing funds without immediate capture, and capturing previously authorized funds directly via the PaymentEscrow smart contract protocol. The endpoints help ensure secure and controlled payment processing, including verifying signatures, and updating payment statuses. - name: Rewards description: >- Endpoints for managing reward operations. These endpoints allow you to independently allocate, distribute, send, and deallocate rewards on previously successful payment operations. - name: Campaigns description: >- Endpoints for managing reward campaigns. Create and manage campaigns that integrate with the Flywheel smart contract to provide reward functionality. Campaigns allow merchants to define reward structures with customizable parameters including reward percentages and maximum limits. - name: coinbase.engine.operator_api.v1.OperatorApiService paths: /api/v1/rewards/allocate: post: tags: - Rewards summary: Allocate rewards description: Allocate rewards for a payment operation. operationId: OperatorApiService_PostAllocateRewards parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true requestBody: content: application/json: schema: type: object properties: paymentOperationId: type: string description: The ID of the payment operation to associate rewards with. title: Payment Operation ID examples: - op-123456 rewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process. title: Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: type: object description: >- Metadata for the reward operations that will be returned in the webhook. title: Metadata examples: - key: value description: Request payload for allocating rewards. title: PostAllocateRewardsRequest required: - paymentOperationId - rewards examples: - paymentOperationId: op-123456 rewards: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: key: value description: Request payload for allocating rewards. required: true responses: '200': description: A successful response. content: application/json: schema: type: object properties: rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - '2024-03-20T00:00:00.000Z' updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - '2024-03-20T00:30:00.000Z' required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - '2024-03-20T00:00:00.000Z' updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - '2024-03-20T00:30:00.000Z' metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - '2024-03-20T00:00:00.000Z' updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - '2024-03-20T00:30:00.000Z' transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - '2024-03-20T00:00:00.000Z' updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - '2024-03-20T00:30:00.000Z' operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' reward: id: rw-123456 metadata: key: value description: >- List of successful reward operations with detailed information. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of reward inputs that were invalid/unable to be processed with detailed reasoning. title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for allocating rewards. title: PostAllocateRewardsResponse examples: - rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: '2024-03-20T00:00:00.000Z' updatedAt: '2024-03-20T00:30:00.000Z' metadata: key: value invalidRewardInputs: - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} security: - Bearer: [] components: securitySchemes: Bearer: type: apiKey description: >- Authorization header using the Bearer scheme. Learn more about JWT tokens in the Coinbase Developer Portal. name: Authorization in: header ````