The newest version of this document can be found online at: https://resources.eprofit.ch/api/manage/transactions
Last modified: 2022-03-10 16:41 ➔ reload

Automated delivery of transactions via API

Other API methods:

API basics

API methods

Add Transactions (POST)

[Base-URL]/transactions/add

Submit customer transactions.

POST data:
You can pass any number of trancactions to this call, chained in an array.
The following example shows all possible combinations of transaction data and a description for each field and case.

[
    // example of a cancellable / mutable transaction with ePROFIT member number, basket, specific location and benefit type "cashback"
    {
        "date": "2018-05-30 10:00:36", // local swiss date / time
        "id": "p987-b12",              // [optional]; your internal id of the transaction for better identification of the transaction in case of errors

        // identification of your location - only needed, if you have more then one local stores / locations
        // use either "locationId" or "locationZip". don't use both at the same time!
        "locationId": "l-1234",        // [optional, if only one location or none]; transactions gets attached to the location with the corresponding id
                                       // the ID can either set via "Set Locations" or it is provided by apNet
        "locationZip": "8200",         // [optional, if only one location or none]; transactions gets attached to the location with the corresponding zip

        // customer identification
        "customerType": "epr",         // [optional]; can be "epr" or "user", depending on the type of the customers identifier you have; Default is "epr"
        "customer": "1529796",         // in case "customerType" is not set or set to "epr" this is the ePROFIT member number
                                       // in case "customerType" is "user" this is an integer ID, delivered by apNet

        // monetary values
        "currency": "CHF",             // if not CHF, amount and cashback get converted to CHF by the API based on daily courses from EZB
                                       // currency code must be an uppercase alphabetical ISO 4217 code
        "amount": 24.6,                // full shopping total, the total the customer has on his bill
        "transactionType": "cashback", // "cashback" means the customer will get cashback later; "instant" means the customer will get a discount right at the point of sales
        "cashback": 2.46,              // [optional if "transactionType" is "cashback"]; profit of the customer; named "cashback" for all transaction types
                                       // if not submitted, cashback gets calculated according to the cashback percentage defined on the partner
                                       // in case "transactionType" is "instant", the rebate amount must be sent as a value in the "cashback" property, as well. There is no separate property for this type of benefit / discount

        // basket
        "items": [                     // [optional]; submit items (of the shopping cart) for displaying purposes to the customer
            {
                "quantity": 2,         // quantity of the same item => number
                "itemNumber": "abc1"   // item number in your system => text
                "amount": 12.3         // full price of the item, if quantity is greater than one, submit still the price per item, not a total => number
                "cashback": 1.23       // [optional]; you can submit a cashback per item, this is just for displaying purposes, you have to calculate the correct total yourself if a total cashback is submitted => number
                "name": "Item 1"       // [optional]; display name of the item for the customer
            },
            {...}
        ],

        // cancellation / mutation
        // if the customer is able to cancel the transaction or a part of it, you HAVE TO set this property and see section "Temporary Transactions" for further processing
        // if you set this property, you HAVE TO "commit" the transaction later (see section "Temporary Transactions"). Otherwise the cashback will never be payed out to the customer !!!
        "isTemporary": true,           // [optional, if the transaction is definitive (immutable and not cancellable)]
        "autoCommit": "2018-07-15",    // [optional, only use if "isTemporary" is TRUE]; local swiss date; automatically commit the transaction at this date. If this date is set, there's no need to commit the temporary transaction via API
    },

    // example of an immutable and not cancellable transaction with user ID (instead of ePROFIT member number; user ID is passed on to online shops via URL parameter),
    // without cashback / benefits value (calculated by the server) and without locationId (only possible if you have only one location or an online shop)
    {
        "date": "2018-05-30 10:00:36",
        "customerType": "user",        // see comment below (property "customer")
        "customer": 1533664,           // in this case the user is identified via his apNet user ID, not via ePROFIT member number
        "currency": "CHF",
        "amount": 53.2,
        "transactionType": "cashback"
    },

    // multiple transactions are possible ( < 200 at a time )
    {
        ...
    }
]

Returned JSON in case of all transactions could be successfully created:

{
    "success": true,
    "errorTransactions": []
}

Returned JSON in case of there were errors with specific transactions:

{
    "success": true,
    "errorTransactions": [{
        "transaction": [... submitted data ...]
        "error": "message describing the problem"
    }, {
        ...
    }]
}

Transactions without errors do not have to be transmitted again.

Some important Error Messages

Dynamic values are marked with {}. Additional Text is marked with [].

Temporary Transactions

You can add temporary transactions. For example if a customers orders multiple items in your shop. You can immediately add a temporary transaction. Temporary transactions can be modified or deleted later. In case the customer sends back some items you can change the amount or delete the entire transaction. When all is done, you have to mark the transaction as definitive.

It is important, that you finally mark transactions as definitive (commit)! If you don't, the customer will not receive any cashback and will see the transaction as temporary forever on his dashboard.
If you delete a transaction, you don't have to mark it as definitive.

Possible Use Cases

Case 1:

  1. Customer orders multiple items -> You add a temporary transaction
  2. Customer orders multiple items -> You update the transaction
  3. Return limit reached -> You commit the transaction and the customer will get his cashback money

Case 2:

  1. Customer orders one item -> You add a temporary transaction
  2. Customer sends the item back -> You delete the transaction

Add

This example is based on the 'Add Transaction' method and shows the ADDITIONAL fields required, to make the transaction temporary!

[Base-URL]/transactions/add

[{
        ...,                       // fields from 'Add Transaction' method
        "id": "p987-b12",          // [required]; in case of a temporary transactions, this identifier is used to modify the transaction later
        "isTemporary": true,       // [required]; otherwise it defaults to a normal definitive transaction
        "autoCommit": "2018-07-15" // [optional]; local swiss date; automatically commit the transaction at this date. If this date is set, there's no need to commit the temporary transaction via API
}, {
    ...
}]

Update (POST)

[Base-URL]/transactions/update/[id, submitted while adding transaction]

{
    "currency": "CHF",         // [required]; if not CHF, amount and cashback get converted to CHF by the API based on daily courses from EZB
                               // currency code must be an uppercase alphabetical ISO 4217 code
    "amount": 13.45,           // [required]; total amount of the transaction
    "cashback": 2.50,          // [optional]; see 'Add Transaction' for details about submitting a cashback or not
    "items": [...],            // [optional]; see 'Add Transaction' for details. Please submit the remaining items of the shopping cart
                               // If items were submitted initially, this property gets MANDATORY, because if it's NULL on update, the initially stored items will get deleted
    "autoCommit": "2018-07-15" // [optional]; see 'Add Transaction' or 'Temporary Transactions' for details. Set to NULL if date must be deleted
}

Delete

[Base-URL]/transactions/delete/[id, submitted while adding transaction]

No POST body required.

Commit / mark as definitive

[Base-URL]/transactions/commit/[id, submitted while adding transaction]

No POST body required.

Get Transaction (GET)

[Base-URL]/transactions/get/[id, submitted while adding transaction]

Useful to check and validate the data of submitted transactions - e.g. during development / testing.

Returned JSON in case of a transaction found:

{
    "id": "p987-b12", // your internal id
    ...               // additional information about the transaction
}

Returned JSON in case of no transaction found:

[]