Overview

Important concepts can be found in this section as well as detailed information on the API endpoints.

Base URL

All URL paths referenced in this document are relative to the following base URL

Available Objects and Methods

The PFLlink API exposes the following objects. In general, all objects are contextualized to the User identified by the Bearer token.

API Reference and Console

For full details of the REST endpoints and their supported operations, see the API Reference at the PFLlink Developer Portal

NOTE:
You must be a registered developer and subscribed to the API to send requests through the interactive API test console.

Swagger File

To view the PFLlink API using the Swagger UI explorer, visit http://petstore.swagger.io/?url=https://pflapi.com/meta/v1/swagger

The Swagger UI explorer offers better documentation on the request and response models used by the API, but it doesn’t allow for you to test calls against the API at this time.

The (production) Swagger 2.0 metadata file can be downloaded from the following URL:

• https://pflapi.com/meta/v1/swagger

Verbose Flag

A handful of the API requests return a subset of available object data by default. By passing an optional GET parameter you can request that full object details be returned. To get full object details pass a GET parameter with a key of ‘verbose’ and a value of ‘true’.

By default, this is set to ‘false’. In general, the default response is enough to generate a user interface but there may be cases where more information is needed. Be aware that setting the verbose flag to ‘true’ will cause the response to be much slower. Use this feature only where appropriate.

The verbose flag is available on the following functions :

• GET /application
• GET /store (only StoreID is returned by default)
• GET /store/{StoreID}/product

Order Billing Variables

The order endpoint payloads can contain billing variables. Billing variables are simply a key / value pair that will be added to the PFL order. Think of them as user-specified meta data; for example, a user might want to include the static value 'Marketing Department : Q1 Budget' on their invoices.

Requirements

• Both a Key and a Value are required
• There is no hard limit to the number of Key/Value pairs that can be added to an order
• Keys and Values are each limited to 255 characters

Below is the payload for the GET /order endpoint for reference on how billing variables are formatted.

  {
  "PageIndex": 0,
  "PageSize": 0,
  "TotalCount": 0,
  "TotalPageCount": 0,
  "HasNextPage": true,
  "HasPrevPage": true,
  "Items": [
    {
      "PartnerOrderReference": "string",
      "ID": "string",
      "StatusDescription": "string",
      "StatusID": 0,
      "Completed": true,
      "OrderNumber": "string",
      "StoreID": "string",
      "Created": "2016-08-18T16:27:22.723Z",
      "Updated": "2016-08-18T16:27:22.723Z",
      "OrderDetails": {
        "Product": {
          "TemplateFields": {},
          "DeliveryMethod": "string",
          "IntelligentMailingSerialNumber": "string",
          "ID": "string",
          "Quantity": 0,
          "FileURL": "string",
          "ProductionSpeedDays": 0
        },
        "Products": [
          {
            "TemplateFields": {},
            "DeliveryMethod": "string",
            "IntelligentMailingSerialNumber": "string",
            "ID": "string",
            "Quantity": 0,
            "FileURL": "string",
            "ProductionSpeedDays": 0
          }
        ],
        "Recipient": {
          "Email": "string",
          "Title": "string",
          "NameFirst": "string",
          "NameLast": "string",
          "CompanyName": "string",
          "AddressLine1": "string",
          "AddressLine2": "string",
          "AddressLine3": "string",
          "City": "string",
          "Province": "string",
          "Postalcode": "string",
          "Country": "string",
          "BusinessPhone": "string",
          "MobilePhone": "string"
        },
        "EddmDeliveryAreas": [
          {
            "PostalCode": "string",
            "CarrierRoute": "string",
            "TargetAudience": "All"
          }
        ],
        "Customer": {
          "NameFirst": "string",
          "NameLast": "string",
          "CompanyName": "string",
          "AddressLine1": "string",
          "AddressLine2": "string",
          "City": "string",
          "Province": "string",
          "PostalCode": "string",
          "Country": "string",
          "Email": "string",
          "Phone": "string"
        },
        "Payments": [
          {
            "ExpectedAmount": 0,
            "ID": "string",
            "Method": "stripe"
          }
        ],
        "PartnerOrderReference": "string",
        "StatusCallbackUrl": "string",
        "StatusDetailsCallbackUrl": "string",
        "BillingVariables": [
        {
        "key": "string",
        "value": "string"
        }
        ]
      },
      "_meta": {
        "Messages": [
          "string"
        ],
        "ChangeType": "Created"
      }
    }
  ]
}

Multiple Recipients Per Order

The GAPI order endpoints support the ability to have multiple recipients per order in which each recipient can receive all or part of the specified products. For example, this functionality makes it possible for 50 people to all get one item or for a certain 25 to get one thing and the other 25 to get another thing (and the 5 magic people in the middle would get both).

Sample Use Cases

• Alice, Barb and Claire can each receive 1 coffee cup and 2 pens (many to many)
• A and B each receive a coffee cup and both C and D get 2 pens (many to one & many to one)
• A, B & C receive cups, but only C gets pens (many to many and one to many)
• A gets 1 cup and 2 pens (one to many)

Requirements / Notes

• If one recipient has a file URL specified then all recipients must.
• FileURL can be specified at the product level to have it effect all recipients. FileURL specified in the limitToRecipients array will then override the product level field.
• All RecipientKeys specified must be unique to the order.
• All addresses must meet PFL API validation standards or the call will fail.
• Ordering the same product twice in a single order is not allowed for any reason (the most common example of this would be differing templates of the same product for different people).
• Because multiple recipients per order are treated as a mailing list, multiple delivery methods are not allowed.
• Only certain delivery methods (USPS and FedEx) are supported for multiple recipient orders. The codes that can be used are listed in the table below.

Available Shipping Methods

Below is a sample payload for the structure of a multiple recipient order. The Quantity field will be computed automatically so it is not recommended that this ever be set manually when using multiple-recipients.

{
    "Items": [{
        "Products": [{
            "DeliveryMethod": "string",
            "ID": "asdf",
            "Quantity": 302,
            "LimitToRecipients": [{
                "RecipientKey": "1234",
                "Quantity": 2
            }, {
                "RecipientKey": "5678",
                "Quantity": 300
            }]
        }, {
            "DeliveryMethod": "string",
            "ID": "xkcd",
            "Quantity": 2,
            "LimitToRecipients": [{
                "RecipientKey": "1234",
                "Quantity": 1
            }, {
                "RecipientKey": "5678",
                "Quantity": 1
            }]
        }, {
            "DeliveryMethod": "USPS",
            "ID": "qwert",
            "Quantity": 3,
            "QuantityPerRecipient": 1
        }],
        "Recipients": [{
            "RecipientKey": "5678",
            "NameFirst": "string",
            "NameLast": "string",
            "AddressLine1": "string"
        }, {
            "RecipientKey": "1234",
            "NameFirst": "string",
            "NameLast": "string",
            "AddressLine1": "string"
        }, {
            "NameFirst": "string",
            "NameLast": "string",
            "AddressLine1": "string"
        }],
    }],
    "MaxRetries": 0,
    "TestMode": true
}

Order Payment Property

The POST /store/{storeID}/order endpoint allows a customer to pay for an order with a credit card by including a Payments property in the payload. One important nuance of the Payments property is that it contains an ExpectedAmount field. The ExpectedAmount field acts as a sanity check for orders that may have a different negotiated price than final price. It is possible to leave this field empty and have the value default to the complete order value. It does not effect what is actually charged. Any value entered in the ExpectedAmount field will be cross-checked against the cost of the order. If a discrepancy between the two is found, it will halt the order until the customer and PFL resolve the different.

The Payment property can be added to the POST /store/{storeID}/order endpoint to allow the customer to pay using a credit card. It is an optional property. A sample payload that includes the Payments property is shown below. Adding the Payments property with the appropriate values will allow the credit card information to be processed and charged.

{
  "Items": [
    {
      "Product": {
        "TemplateFields": {},
        "DeliveryMethod": "string",
        "ID": "string",
        "Quantity": 0,
        "FileURL": "string"
      },
      "Products": [
        {
          "TemplateFields": {},
          "DeliveryMethod": "string",
          "ID": "string",
          "Quantity": 0,
          "FileURL": "string"
        }
      ],
      "Recipient": {
        "Email": "string",
        "Title": "string",
        "NameFirst": "string",
        "NameLast": "string",
        "CompanyName": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "AddressLine3": "string",
        "City": "string",
        "Province": "string",
        "Postalcode": "string",
        "Country": "string",
        "BusinessPhone": "string",
        "MobilePhone": "string"
      },
        "Payments": [
        {
        "ExpectedAmount": 0,
        "ID": "string",
        "Method": "stripe"
        }
      ],
      "PartnerOrderReference": "string",
      "StatusCallbackUrl": "string"
    }
  ],
  "MaxRetries": 0,
  "TestMode": true
}
        

The following notes contain details on the three fields included in the Payments property and their particular quirks:

ExpectedAmount

This is not a required field and should only be used if there is a chance that the negotiated value of the order and the actual price of the order may differ (as may be the case when the actual order size is ambivalent). Adding a value here will cross-check this value against the calculated actual cost of the order. If the two are the same, the order will proceed as expected. If the two differ, the order will be halted until the customer and PFL have a chance to sort out the difference. If no value is entered, it will default to null and the order will proceed as expected, using the cost of the order as the amount to be charged to the credit card.

ID

The ID is a single use token returned by the Stripe API. This is not the credit card number. More details on how the ID is generated from Stripe can be found here.

Method

PFL uses Stripe APIs for credit card payments. Information on the how the Stripe APIs work can be found here and it is important to note that the Payment property currently only accepts the Stripe Production White Label public token.

Order Status Event Codes

As an order goes through all its stages from beginning to end, there are various status events that indicate its progress.

Status Event Codes

2000 : Order Placed
A 2000 status code indicates that the order has been successfully processed by PrintingForLess and is now in progress. From here, the order will sequentially progress through the remaining stages of production and shipping until the customer has received the product(s) unless someone cancels the order.
There is a callback URL with each order that can potentially result in communication failures between the PFL API and the associated application. This simply means that it is possible for the order to successfully go to the next stage of production or delivery but not correctly in the application.
If order status updates stop showing up in the client application, it is likely this occurred. Automatic retries to communicate the correct status to the application occur in 60 minute increments and will retry 3 times. Any callback communication failures between the PFL API and the application can be viewed in the order history.

Product Shipping Methods

There is one default domestic shipping method and one default international shipping method. Although that's the case and the expected behavior might be a single entry returned for each, it is possible for the API to return multiple entries for any international shipping method. Multiple entries are returned when there is more than one country because it is possible for the price to vary by country. In addition, a null entry will always be returned per type of shipping method (both international and domestic). As you can see in the code below, the five highlighted entries with are identical (i.e. the same default international shipping method) with their only variation occurring in the country and country code returned. The entries that are not highlighted are a shipping method that is not the default, but are also all the same type, Economy.

    {
        "DeliveryMethodCode": "FDXIP",
        "Description": "FedEx International Priority",
      "Price": 0.0,
      "Country": null,
      "CountryCode": null,
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
        "IsDefault": true
    },
    {
        "DeliveryMethodCode": "FDXIP",
        "Description": "FedEx International Priority",
      "Price": 0.0,
      "Country": "Australia",
      "CountryCode": "AU",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
        "IsDefault": true
    },
    {
        "DeliveryMethodCode": "FDXIP",
        "Description": "FedEx International Priority",
      "Price": 0.0,
      "Country": "Canada",
      "CountryCode": "CA",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
        "IsDefault": true
    },
    {
        "DeliveryMethodCode": "FDXIP",
        "Description": "FedEx International Priority",
      "Price": 0.0,
      "Country": "Netherlands",
      "CountryCode": "NL",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
        "IsDefault": true
    },
    {
        "DeliveryMethodCode": "FDXIP",
        "Description": "FedEx International Priority",
      "Price": 0.0,
      "Country": "Norway",
      "CountryCode": "NO",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
        "IsDefault": true
    },
    {
      "DeliveryMethodCode": "FDXIE",
      "Description": "FedEx International Economy",
      "Price": 0.0,
      "Country": null,
      "CountryCode": null,
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
      "IsDefault": false
    },
    {
      "DeliveryMethodCode": "FDXIE",
      "Description": "FedEx International Economy",
      "Price": 0.0,
      "Country": "Australia",
      "CountryCode": "AU",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
      "IsDefault": false
    },
    {
      "DeliveryMethodCode": "FDXIE",
      "Description": "FedEx International Economy",
      "Price": 0.0,
      "Country": "Canada",
      "CountryCode": "CA",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
      "IsDefault": false
    },
    {
      "DeliveryMethodCode": "FDXIE",
      "Description": "FedEx International Economy",
      "Price": 0.0,
      "Country": "Netherlands",
      "CountryCode": "NL",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
      "IsDefault": false
    },
    {
      "DeliveryMethodCode": "FDXIE",
      "Description": "FedEx International Economy",
      "Price": 0.0,
      "Country": "Norway",
      "CountryCode": "NO",
      "Created": "2016-02-08T14:34:50.067",
      "LocationType": "international",
      "IsDefault": false
    }

Product Templates

Some products can be configured to include template fields. These fields need to have populated values when an order is submitted. To check if a product has a template field look for "HasTemplate": true in the response from GET /store/{id}/product

Products that have templates will return an array of template fields:

"TemplateFields": [
      {
        "Required": false,
        "Type": "SINGLELINE",
        "SubType": "A",
        "FieldName": "FIRST_NAME",
        "Prompt": "First Name",
        "DefaultValue": "",
        "OrgValue": "PFL"
      },
      {
        "Required": false,
        "Type": "SINGLELINE",
        "SubType": "A",
        "FieldName": "EVENT_NAME",
        "Prompt": "Event Name",
        "DefaultValue": "",
        "OrgValue": "Resource Celebration"
      },
      {
        "Required": false,
        "Type": "SINGLELINE",
        "SubType": "A",
        "FieldName": "SALESPERSON",
        "Prompt": "Salesperson",
        "DefaultValue": "",
        "OrgValue": "Seth"
      }
    ],

The contents of each field should provide enough information to create a useful user interface for the field

• Required: indicates if the field is required in the order payload
• FieldName: the name of the field. this is the key to use with an order
• Prompt: a user-readable name for the field. this can be used as a label in a user interface
• DefaultValue: if nothing is entered by the user the field should revert to this value
• OrgValue: tbd
• Type & SubType: see below

Types & SubTypes

Template Field Types indicate the type of user interface that should be used to gather the data from the user. The types are (with indented subtypes):

• SINGLELINE: a single line of user input
  
  • A: the value should be alpha (a-z) or alphanumeric (a-z,0-9) characters
  • I: the value should be an interger (0-9)
  • N: the value should be a decimal (123.12)
• MULTILINE: multiple lines of text should be entered
• PICKLIST: a selection should be made from a dropdown of available options
  
  • DROPLIST: a dropdown list should be displayed
  • LISTBOX: a listbox should be displayed
  • MULTI: a multi-select listbox should be displayed
• GENDER: the value should indicate gender. Values are ‘male’ or ‘female’
  
  • M_F: possible values are ‘m’ or ‘f’
• YESNO: a boolean input should be gathered. Values are ‘true’ or ‘false’
  
  • 1_0: values are ‘1’ or ‘0’
  • T_F: values are ‘T’ or ‘F’
  • Y_N: values are ‘Y’ or ‘N’
  • YES_NO: values are ‘YES’ or ‘NO’
• GRAPHICUPLOAD: can have a url provided and the printed material will contain the image at that location
• GRAPHICPICKLIST: an image should be selected from a list
• SEPARATOR: a line break will be inserted at this point in the final document

Submitting an Order

Values for template fields are included in an Order by populating a Key/Value pair in the product object on the request. The Key is the FieldName value from the template definition and the value is the data gathered from the user:

{
    "Items": [{
        "Product": {
            "TemplateFields": {
                "FieldName": "Value"
            },
            "DeliveryMethod": "string",
            "ID": "string",
            "Quantity": "0"
        }
        ...
    }]
}

Generating Proofs (via URL)

Passing in key=value pairs of template fields will return a rendered versions of the product via a URL. This only works for products that have template fields. Additionally, the template cannot be completely blank (which would hopefully be an invalid use case anyway); at least one of the template fields must contain data.

{
    "FIRST_NAME": "John"
    "SALESPERSON": "Jeor Mormont"
    "EVENT_NAME": ""
}

The response payload includes the following:

Administrator Permissions

The administrator role contains this entire list of permissions. (The default and report permissions sets (roles) each contain a specific subset of these.) The administrator can dole specific permissions from this list out as needed to grant users access to the functionality available in particular endpoints.

For example, an admin can grant one of the store permissions to a user by using the POST /store/{storeID}/user function. Similarly, the admin can grant one of the application permissions to a user with the POST /application/{applicationID}/user function.

All Permissions

store.all.read
store.all.write
store.all.delete
store.self.read
store.self.write
store.self.delete
order.all.read
order.all.write
order.all.delete
order.self.read
order.self.write
order.self.delete
application.all.read
application.all.write
application.all.delete
application.self.read
application.self.write
application.self.delete

* If no association exists between the two, you can request than an admin create the relationship.

Applications only need to be associated to a store if the application is going to authenticating (using client credentials rather than user credentials). In that case the user who is configuring the application must have application.*.write and store.write.

Permission Sets

Default Permissions Set

GET /application/{applicationID}/icon
GET /application/{applicationID}/user
GET /application/{applicationID}/user/{userID}
GET /application/{applicationID}
GET /application
POST /application
GET /delivery/eddm
GET /delivery/eddm/{postalCode}
GET /delivery/eddm/{postalCode}/route/{carrierRouteID}
GET /stats
GET /stats/store/{storeID}
GET /store/{storeID}/order/{orderID}/status
GET /store/{storeID}/order
GET /store/{storeID}/order/{orderID}
GET /store/{storeID}/product
GET /store/{storeID}/product/{productID}
POST /store/{storeID}/product/{productID}/proof
POST /store/invite
GET /store/{storeID}/user
GET /store/{storeID}/user/{userID}
GET /store
GET /store/{storeID}
GET /user/roles
GET /user
POST /user
GET /user/{userID}

Report Permissions Set

GET /application/{applicationID}/user
GET /application/{applicationID}/user/{userID}
GET /store/{storeID}/order/{orderID}/status
GET /store/{storeID}/order
GET /store/{storeID}/order/{orderID}
GET /store/{storeID}/user
GET /store/{storeID}/user/{userID}