Contents x
    Approve, decline, amend batch transactions for a given advertiser
    • 03 Dec 2024
    • Dark
      Light
    Contents

    Approve, decline, amend batch transactions for a given advertiser

    • Updated on 03 Dec 2024
    • Dark
      Light
    Article summary

    Post
    /advertisers/{advertiserId}/transactions/batch
    Header parameters
    Authorization
    string

    accessToken

    Path parameters
    advertiserId
    integer (int64) Required

    advertiserId

    Request Body:
    The request body contains an array of transaction objects (a single bulk request is limited to 40 thousand transaction objects). Each object represents the action to be executed, the transaction, and if required, any additional parameters. Transactions are identified either by transactionId, or by orderRef, transactionDate, and timezone. 

    "transactionId": "484816099",


    "orderRef": "123ABC555",

    "transactionDate": "2017-02-20T22:04:00",

    "timezone": "Europe/Paris"

    Available Operations

    Approve

    Approve by transactionId:

    {  

    "action": "approve",  

    "transaction": {    

    "transactionId": 1234567  }

    } 

    Approve by orderRef, transactionDate, and timezone:

    {  

    "action": "approve", 

     "transaction": {   

     "orderRef": "123ABC555",   

     "transactionDate": "2017-02-20T22:04:00",   

     "timezone": "Europe/Paris" 

     }

    }

    Decline

    Decline by transactionId:

    {
      "action": "decline",
      "transaction": {
        "transactionId": 1234567,
        "declineReason": "order returned"
      }
    }

    Decline by orderRef, transactionDate, and timezone:

    {
      "action": "decline",
      "transaction": {
        "orderRef": "123ABC555",
        "transactionDate": "2017-02-20T22:04:00",
        "timezone": "Europe/Paris",
        "declineReason": "order returned"
      }
    }

    Amend Sale Amount

    Amend sale amount by transactionId:

    {
      "action": "amend",
      "approve": false,
      "transaction": {
        "transactionId": 1234567,
        "amendReason": "partial return",
        "currency": "EUR",
        "saleAmount": 55.96,
        "transactionParts": [
          {
            "amount": 44.76,
            "commissionGroupCode": "DEFAULT"
          },
          {
            "amount": 11.20,
            "commissionGroupCode": "EXISTING"
          }
        ]
      }
    }

    Amend sale amount by orderRef, transactionDate, and timezone:

    {
      "action": "amend",
      "approve": false,
      "transaction": {
        "orderRef": "123ABC555",
        "transactionDate": "2017-02-20T22:04:00",
        "timezone": "Europe/Paris",
        "amendReason": "partial return",
        "currency": "EUR",
        "saleAmount": 55.96,
        "transactionParts": [
          {
            "amount": 44.76,
            "commissionGroupCode": "DEFAULT"
          },
          {
            "amount": 11.20,
            "commissionGroupCode": "EXISTING"
          }
        ]
      }
    }

    Note: To ensure the integrity of amendment transactions, the sum of the transaction parts must be identical to the saleAmount. Otherwise, the "DEFAULT" commissionGroup is adjusted automatically to balance possible differences.
    If you set the approve parameter to "true", the API first amends the transaction, and then approves it immediately after that.

    Amend Tracking Parameter - Custom Parameter

    This operation can be used to UPDATE or CREATE custom parameter values that advertisers parse in our Tracking Parameter. Within the API call, you specify which custom parameter key you want to update/create and provide the value. Advertisers cannot DELETE or send blank custom parameter values.

    Amend custom parameter by transactionId:

    [
        {
            "action": "amendTrackingParameters",
            "transaction": {
                "transactionId": 1234567,
                "amendReason": "incorrect check-in date",
                "customParameters": {
                    "put": {
                        "3": "CardPayment",
                        "5": "20/07/2024",
                        "10": "No Refund"
                    }
                }
            }
        }
    ]

    Amend custom parameter by orderRef, transactionDate, and timezone:

    [
        {
            "action": "amendTrackingParameters",
            "transaction": {
                "orderRef": "123ABC555",
                "transactionDate": "2017-02-20T22:04:00",
                "timezone": "Europe/Paris",
                "amendReason": "update customer type and membership",
                "customParameters": {
                    "put": {
                        "2": "NEW",
                        "6": "GoldMembership",
                    }
                }
            }
        }
    ]

    Note: Awin will actively work on removing the below conditions after the feature has gone live. Till then, if any of these conditions are met Awin will return a 422 error code. Please see the list of criteria below:

    - CPO advertiser.
    - Have previously had their sale amount or commission amended.
    - Any shared transactions.
    - Transactions involving subnetwork publishers.
    - Transactions with the sale date before June 2023.

    Body parameters

    transactions

    Array of object
    object
    array
    boolean
    bigDecimal
    boolean
    bigInteger
    boolean
    binary
    boolean
    boolean
    boolean
    containerNode
    boolean
    double
    boolean
    empty
    boolean
    float
    boolean
    floatingPointNumber
    boolean
    int
    boolean
    integralNumber
    boolean
    long
    boolean
    missingNode
    boolean
    nodeType
    string
    Valid values[ "\"ARRAY\"", "\"BINARY\"", "\"BOOLEAN\"", "\"MISSING\"", "\"NULL\"", "\"NUMBER\"", "\"OBJECT\"", "\"POJO\"", "\"STRING\"" ]
    null
    boolean
    number
    boolean
    object
    boolean
    pojo
    boolean
    short
    boolean
    textual
    boolean
    valueNode
    boolean
    Responses
    200

    OK

    Expand All
    object
    body
    object
    statusCode
    string
    Valid values[ "\"100 CONTINUE\"", "\"101 SWITCHING_PROTOCOLS\"", "\"102 PROCESSING\"", "\"103 CHECKPOINT\"", "\"200 OK\"", "\"201 CREATED\"", "\"202 ACCEPTED\"", "\"203 NON_AUTHORITATIVE_INFORMATION\"", "\"204 NO_CONTENT\"", "\"205 RESET_CONTENT\"", "\"206 PARTIAL_CONTENT\"", "\"207 MULTI_STATUS\"", "\"208 ALREADY_REPORTED\"", "\"226 IM_USED\"", "\"300 MULTIPLE_CHOICES\"", "\"301 MOVED_PERMANENTLY\"", "\"302 FOUND\"", "\"302 MOVED_TEMPORARILY\"", "\"303 SEE_OTHER\"", "\"304 NOT_MODIFIED\"", "\"305 USE_PROXY\"", "\"307 TEMPORARY_REDIRECT\"", "\"308 PERMANENT_REDIRECT\"", "\"400 BAD_REQUEST\"", "\"401 UNAUTHORIZED\"", "\"402 PAYMENT_REQUIRED\"", "\"403 FORBIDDEN\"", "\"404 NOT_FOUND\"", "\"405 METHOD_NOT_ALLOWED\"", "\"406 NOT_ACCEPTABLE\"", "\"407 PROXY_AUTHENTICATION_REQUIRED\"", "\"408 REQUEST_TIMEOUT\"", "\"409 CONFLICT\"", "\"410 GONE\"", "\"411 LENGTH_REQUIRED\"", "\"412 PRECONDITION_FAILED\"", "\"413 PAYLOAD_TOO_LARGE\"", "\"413 REQUEST_ENTITY_TOO_LARGE\"", "\"414 URI_TOO_LONG\"", "\"414 REQUEST_URI_TOO_LONG\"", "\"415 UNSUPPORTED_MEDIA_TYPE\"", "\"416 REQUESTED_RANGE_NOT_SATISFIABLE\"", "\"417 EXPECTATION_FAILED\"", "\"418 I_AM_A_TEAPOT\"", "\"419 INSUFFICIENT_SPACE_ON_RESOURCE\"", "\"420 METHOD_FAILURE\"", "\"421 DESTINATION_LOCKED\"", "\"422 UNPROCESSABLE_ENTITY\"", "\"423 LOCKED\"", "\"424 FAILED_DEPENDENCY\"", "\"425 TOO_EARLY\"", "\"426 UPGRADE_REQUIRED\"", "\"428 PRECONDITION_REQUIRED\"", "\"429 TOO_MANY_REQUESTS\"", "\"431 REQUEST_HEADER_FIELDS_TOO_LARGE\"", "\"451 UNAVAILABLE_FOR_LEGAL_REASONS\"", "\"500 INTERNAL_SERVER_ERROR\"", "\"501 NOT_IMPLEMENTED\"", "\"502 BAD_GATEWAY\"", "\"503 SERVICE_UNAVAILABLE\"", "\"504 GATEWAY_TIMEOUT\"", "\"505 HTTP_VERSION_NOT_SUPPORTED\"", "\"506 VARIANT_ALSO_NEGOTIATES\"", "\"507 INSUFFICIENT_STORAGE\"", "\"508 LOOP_DETECTED\"", "\"509 BANDWIDTH_LIMIT_EXCEEDED\"", "\"510 NOT_EXTENDED\"", "\"511 NETWORK_AUTHENTICATION_REQUIRED\"" ]
    statusCodeValue
    integer (int32)

    Common Response Codes 

    The following table contains a list of possible response reasons for common response codes that may appear when using the API:

    Response CodeResponse MessagePossible Response Reason
    200OKThe transaction was validated as desired.
    304NOT_MODIFIEDThe transaction was already in the desired commission state. For example, trying to decline a declined transaction.
    400JSON parse errorEnsure that your JSON object is enclosed by square brackets.
    404NOT_FOUNDThe transactionId or (orderRef, transactionDate, timezone) did not correspond to a transaction.
    422UNPROCESSABLE_ENTITYUnable to complete the request due to the current transaction state. For example, trying to approve a declined transaction. 
    Was this article helpful?
    What's Next

    © 2024, AWIN Ltd. All rights reserved. Awin is part of Axel Springer Group. No part of this publication may be reproduced, translated, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior permission of the copyright owner.