Create Transaction Type

Creates a new transaction type with the given name in the account.

Request

POST https://api.maileon.com/1.0/transactions/types

Media type: application/vnd.maileon.api+xml or application/json
This method can be called with either XML of media type application/vnd.maileon.api+xml or with JSON of media type application/json. Both variants of the method differ slightly in how a definition of the transaction type attributes is arrived at. Generally, the XML request offers more options for configuring transaction attributes.

XML specification

A transaction type definition contains a set of basic settings for the transaction type and a set of attributes which will contain the data later on. The following table defines the attributes for the transaction type itself:

Any number of attributes can be specified. The following table explains the child elements of <attribute>:

{
  "customer" : {
    "firstname" : "John",
    "Lastname" : "Doe"
  }
  ...
}

<transaction_type>
   <name>Order</name>
   <archivingduration>7</archivingduration>
   <description>An order transaction</description>
   <attributes>
      <attribute>
         <name>customer.firstname</name>
         <description>The first name of the customer</description>
         <type>string</type>
         <required>true</required>
      </attribute>
      <attribute>
         <name>customer.lastname</name>
         <description>The last name of the customer</description>
         <type>string</type>
         <required>true</required>
      </attribute>
      <attribute>
         <name>date_valid</name>
         <type>timestamp</type>
         <required>true</required>
      </attribute>
      <attribute>
         <name>total</name>
         <type>double</type>
         <required>true</required>
      </attribute>
      <attribute>
         <name>discount</name>
         <type>float</type>
         <required>false</required>
      </attribute>
      <attribute>
         <name>num_products</name>
         <type>integer</type>
         <required>false</required>
      </attribute>
      <attribute>
         <name>order_content</name>
         <type>json</type>
         <required>true</required>
      </attribute>
   </attributes>
</transaction_type>

Defining a transaction type using a JSON data example

An easier, if less flexible way of defining a transaction type is by submitting a JSON body of the following form:

{ 
    "name" : "Order",
    "content" :  {
        "currency" : "$",
        "shipping_address" : {
            "line1" : "512 Means St NW Ste",
            "line2" : "404",
            "line3" : "Suite 404",
            "line4" : "Atlanta, Georgia 30318",
            "line5" : "United States"
        },
        "billing_address" : {
            "line1" : "Atlanta, Georgia 30307",
            "line2" : "United States"
        },
        "subtotal" : 54.98,
        "shipping" : 0.00,
        "tax" : 0.00,
        "discount" : 0.00,
        "total" : 54.98,
        "item" : [
            {
            "title" : "Striped Down Cardigan",
            "url" : "http://....",
            "image" : "http://...",
            "details" : "Size L",
            "categories" : ["SizeL", "Woman"],
            "quantity" : 1,
            "price" : 34.99
            },
            {"title" : "Three Little Birdies Wall Hook",
            "url" : "http://....",
            "image" : "http://...",
            "details" : "Color No Color",
            "categories" : ["Furniture"],
            "quantity" : 1,
            "price" : 19.99
            }
        ]
    }
}

In this form of the method, an example of the JSON that would be submitted to Create Transactions is provided in the content attribute of the JSON request body. The system will then extract attribute definitions from the example transaction content according to the following rules:

– all elements are converted to attributes with a name that corresponds to their path in the JSON syntax tree

– the type of the attributes is defined as follows:

– Strings are mapped to string

– Floating-point numbers are mapped to double

– Natural numbers are mapped to integer

– Booleans are mapped to boolean

– Lists are mapped to json

– all attributes are created as optional (i.e. with required=false)

Note that it is impossible to create mandatory attributes, as well as attributes of type float or timestamp using this technique. Since it is impossible to change a transaction type once it is defined, we recommend using the XML body format instead if you need any of these features.

Response

Special Attributes

There is a special attribute called “transaction_id”. The attribute has to be specified like every other text attribute when creating the transaction type. This attribute is always limited to 1000 characters, ignoring the storeOnly setting. If a transaction is sent to Maileon and the “transaction_id” attribute is set, this value can be returned using the Maileon webhooks. So, if you e.g. register a webhook for bounces, your system will be notified with the exact id that was specified in the transaction, so it should be unique for each call. Also a header “X-Transaction” will be added to the mailings, so manual replies can also be assigned to a specific mail.
If attribute „transaction_id“ is specified, it will also be returned with the report when submitting transactions to be able to know which report belonged to exactly which transaction data.