Create Single Purchase

This function is used to create a purchase for a customer. The purchase will be added in draft status and must be finalized before it charges against the customer account.

URL Parameters

Parameter NameTypeDescriptionRequired
viewEnum: {
sideeffects
}
When included and set to "sideeffects" the response will include a sideeffects object showing the resulting draft invoiceOptional
previewBooleanIf true, no purchase will be created. Instead a preview purchase will be returned containing an invoicePreview objectOptional
currency3 character ISO currency codeIf preview is set to true and no customerId is supplied in the body, this is a way to preview the invoice in the specified currency. The currency must be configured for your Fusebill accountOptional

Request Parameters

PropertyTypeDescriptionRequired
customerIdIntegerThis is the ID of the Customer making the purchaseYes, unless preview=true is set
taxationAddressObject. Defined belowIf preview=true this address is used to calculate taxes for the draft invoice preview. This allows for a tax preview without needing a customer ID.Optional
productIdIntegerThis is the unique ID of the product this purchase is for.Yes
nameStringThis is an override of the name of the purchase. This is customer facing and appears in Invoices. [Max Length: 2000]Yes
quantityDecimalThe quantity being purchased. Used by the pricing model and price ranges to calculate the overall price. If the purchase is using tracked quantities, leave this nullOptional
targetOrderQuantityDecimalThe number of tracked items which must be on this purchase in order to be considered fulfilled. If this is not met, the purchase cannot be finalized. Cannot be used for purchases which are not tracking items.Optional
descriptionStringThis is the description of the purchase. This is customer facing and appears on Invoices. [Max Length: 250 characters]
Optional
overridePriceRangesList of objects. Defined belowThe price ranges used to determine the amount to charge. For the standard pricing model, this is a single range from 0 to infinity with a single price. This is an override just for this purchase.Optional
pricingModelTypeEnum: {Tiered, Volume, Standard, Stairstep}Can be used to override the pricing model being used just for this purchase.Optional
customFieldsList of objects. Defined belowThis is a list of the custom fields attached to this purchase.Optional
discountslist of objects. Defined belowThis is a list of discounts to be applied to this purchase.Optional
productItemsList of objects. Defined belowThis is a list of the Purchase Product Items (tracked items) associated to this purchase.Optional
couponCodesList of stringsEach string is a coupon code instructing Fusebill which coupon should be applied to the purchaseOptional
earningSettingsObject. Defined belowControls how this purchase earns. Defaults to the catalog optionsOptional
netsuiteLocationIdStringThe location of this purchase in Netsuite. [Max Length: 100 characters]Optional

Taxation Address Fields

PropertyTypeDescription
line1StringStandard line 1 of an address.

[Max Length: 60]
line2StringStandard line 2 of an address.

[Max Length: 60]
countryIdIntegerThe ID of the country. Retrievable with the Read Country ID call.
stateIdIntegerThe ID of the state, province, or territory. Retrievable with the Read Country ID call.
cityStringThe city of the Customer.
postalZipStringThe postal code or zip code.
[Max Length: 10]

Override Price Ranges Fields

PropertyTypeDescription
minDecimalThe lower bound of the range
maxDecimalThe upper bound of the range. Null is interpreted as infinity
amountDecimalThe price for this range

Custom Field Object

PropertyTypeDescription
keystringThis is the unique key of the Custom Field
valuestringThis is the value you wish to update the custom field to. This will always be the string version of the value. If you wish to pass a number, for example, pass it as "123". Likewise, a DateTime would be passed as "2014-06-26T04:00:00". We will use the known data type of the custom field to properly convert the String to a Number, DateTime, etc.
[Max Length: 1000 characters]

Discounts Fields

PropertyTypeDescription
discountTypeEnum: {Percentage, Amount, AmountPerUnit}Indicates how amount is interpreted for calculating the discount
amountDecimalThe dollar amount or percentage, depending on discountType

Product Items Fields

PropertyTypeDescription
referenceStringThe unique reference for this tracked item [Max Length: 255 characters]
nameStringThe name of this tracked item [Max Length: 100 characters]
descriptionStringThe description for this tracked item [Max Length: 255 characters]

Earning Settings Object

PropertyTypeDescription
earningIntervalEnum: {Monthly, Yearly}Indicates whether the custom earning period (if a custom earning period is being used) is measured in years or months
earningNumberOfIntervalsIntegerThe number of earningIntervals that constitute the period this purchase earns over
earningTimingIntervalEnum:{Daily, Monthly, Yearly, Interval, DoesNotEarn, EarnImmediately}Indicates how to divide the custom period if a custom period is being used, indicates the purchase does not earn, or indicates that the purchase earns immediately
earningTimingTypeEnum:{StartOfInterval, EndOfInterval, DoesNotEarn}Indicates where in the interval the earning occurs, if custom earning periods are being used
Examples
curl -X POST "https://secure.fusebill.com/v1/Purchases" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{customerId:{CustomerId},productId:{ProductId},name:'purchase'}"
//Json Payload
string jsonData = "{customerId:{CustomerId}, productId:{ProductId}, name:'purchase'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://secure.fusebill.com/v1/Purchases");
//Add Content type
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic " + apiKey);
//Set request method
request.Method = "POST";
//Add the json data to request
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
  streamWriter.Write(jsonData);
  streamWriter.Flush();
  streamWriter.Close();
}
//Perform the request
var httpResponse = (HttpWebResponse)request.GetResponse();
//Record the response from our request
var result = "";
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
  result = streamReader.ReadToEnd();
}
#Import library JSON
import json
#Import library Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in a dictionary to the Payload parameter
payload = {"customerId":{id},"productId":{id},"name": "product-3"}
#Pass in your URI, Payload and Headers
r = requests.post('https://secure.fusebill.com/v1/purchases', data=json.dumps(payload), headers=headers)
print(r.content)
{
  "customerId": 655642,
  "productId": 46818,
  "name": "Hardware",
  "quantity": 3
}
{
  "customerId": 655642,
  "productId": 46818,
  "name": "Hardware",
  "description": "Desktop Collection",
  "overridePriceRanges": [
    {
      "min": 0,
      "max": null,
      "amount": 299.99
    }
  ],
  "pricingModelType": "Standard",
  "customFields": [
    {
      "key": "Sales Rep",
      "value": 1235
    }
  ],
  "discounts": [
    {
      "discountType": "Percentage",
      "amount": 50
    }
  ],
  "productItems": null,
  "couponCodes": [
    "code1"
  ],
  "earningSettings": {
  	"earningInterval": "Monthly",
  	"earningNumberOfIntervals": 1,
	  "earningTimingInterval": "Daily",
  	"earningTimingType": "StartOfInterval"
  },
  "netsuiteLocationId":"12"
}
{
  "customerId": 655642,
  "productId": 46818,
  "name": "Hardware",
  "productItems": [
    {
      "reference": 45678913,
      "name": "Keyboard",
      "description": "Model KEYQWERT 9000"
    },
    {
      "reference": 156489,
      "name": "Keyboard",
      "description": "Model KEYQWERT 9001"
    }
  ]
}
Response
{
    "customerId": 12762177,
    "code": "device",
    "effectiveTimestamp": "2019-11-11T19:39:55",
    "taxableAmount": 15,
    "amount": 15,
    "modifiedTimestamp": "2019-11-11T19:40:07.963",
    "salesforceId": "b045a250231VC4RCAW",
    "netsuiteLocationId": "12",
    "productId": 25309384,
    "name": "Fitness Tracker",
    "description": "Model 5000",
    "status": "Purchased",
    "quantity": 1,
    "targetOrderQuantity":null,
    "isTrackingItems": false,
    "pricingModelType": "Standard",
    "customFields": [],
    "discounts": [],
    "priceRanges": [
      {
        "min": 0,
        "max": null,
        "amount": 15,
        "conditionAmount": null,
        "variableAmount": null
      }
    ],
    "productItems": [],
    "couponCodes": [],
    "earningSettings": {
      "earningInterval": "",
      "earningNumberOfIntervals": null,
      "earningTimingInterval": "EarnImmediately",
      "earningTimingType": "StartOfInterval"
    },
    "id": 1616831,
    "uri": "https://secure.fusebill.com/v1/Purchases/1616831"
  }
{
    "ErrorId": 0,
    "HttpStatusCode": 400,
    "Errors": [
        {
            "Key": "Api Error",
            "Value": "Quantity is not valid when the product is tracking unique items"
        }
    ]
}
Language
Authorization