Table of contents
Data sources
Once you set up your Recurly integration, Leapfin will receive relevant data objects from Recurly's versioned API. The following object types are requested from a respective site and subdomain configured in Recurly:
To learn more about the API version and respective endpoints, click here.
Invoice
Invoices in Recurly represent any billing event involving credits or charges, transactions, and credit payments for the event. Leapfin imports legacy and the latest up-to-date form of invoices for a particular site and account configured in Recurly. To learn more about the endpoint from which data is received, click here.
Note: Invoices created before the Credit Invoices feature was enabled on a Recurly site will have a type = "legacy".
Line Item
Line Items in Recurly represent charges and credits on a customer's invoice. Typically, these are accounted for with the Invoice object mentioned above but there are some scenarios in which line items do not appear on an invoice including adjustments issued for previously posted line items.
Mapping Logic
Please note the following about sensitivity and date format:
Sensitivity: The following data fields are removed to avoid ingesting sensitive data into Leapfin:
email
cc_emails
first_name
last_name
address
shipping_addresses
billing_info
hosted_login_token
billing_address
payment_method
ip_address_v4
ip_address_country
shipping_address
Date Format: All date fields in Recurly objects are in datetime format with timezone (e.g. "2011-11-23T03:01:39Z"). They are converted to each organization's timezone when data is mapped in.
recurly-invoice
Leapfin retrieves a list of invoices from Recurly and each object is imported as a recurly-invoice record. Each object contains all the necessary data to create the following Leapfin data types:
Create an Invoice
Leapfin will create an invoice record if recurly-invoice.type = "charge".
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "invoice" |
id | recurly-invoice.id
|
externalSubtotal | recurly-invoice.subtotal
|
externalTotal | recurly-invoice.total
|
currencyCode | recurly-invoice.currency
|
date | recurly-invoice.created_at
|
status | if recurly-invoice.state in ["pending", "processing", "past_due"], status = "open" else if recurly-invoice.state = "paid", status = "paid" else if recurly-invoice.state = "failed", status = "uncollectible"
|
issuedDate | recurly-invoice.created_at
|
dueDate | recurly-invoice.due_at
|
uncollectibleDate | if recurly-invoice.state = "failed", uncollectibleDate = recurly-invoice.closed_at (need data format conversion) else, uncollectibleDate = null
|
paidDate | |
exchangeRates | null |
customFields | type = recurly-invoice.type
origin = recurly-invoice.origin
invoiceNumber = recurly-invoice.number
customerNotes = recurly-invoice.customer_notes
|
links | Add a link to the associated Customer record with: |
Create a Line Item
Note: For invoices of type "charge", line-item type can only be "charge" (i.e. non-negative amount)
Leapfin will process each lineitem object defined in recurly-invoice.line_items.data[] and create a lineItem record if lineitem.type = "charge" AND leapfinInvoice.collectionMethod != "Manual"
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "lineItem" |
id | lineitem.id
|
amount | lineitem.subtotal
|
currencyCode | lineitem.currency
|
date | lineitem.created_at
|
description | lineitem.description
|
discountAmount | lineitem.discount
|
quantity | lineitem.quantity
|
startDate | lineitem.start_date
|
endDate | lineitem.end_date
By default, Leapfin subtracts one day from the line item end date when importing. |
exchangeRates | none |
customFields | taxAmount = lineitem.tax
netAmount = lineitem.amount
appliedCreditAmount = lineitem.credit_applied
type = lineitem.type
origin = lineitem.origin
subscriptionId = lineitem.subscription_id
productCode = lineitem.product_code
planCode = lineitem.plan_code
addonCode = lineitem.add_on_code
|
links | Add a link to the associated Invoice record with: objectType = "invoice" id = lineitem.invoice_id
|
Create a Tax
Leapfin will process each lineitem object defined in recurly-invoice.line_items.data[] and create a Tax record if lineitem.tax!= 0
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "tax" |
id | lineitem.id
|
amount | lineitem.tax
|
currencyCode | lineitem.currency
|
date | lineitem.created_at
|
description | " " |
exchangeRates | none |
customFields | rate = lineitem.tax_info.rate
type = lineitem.tax_info.type
region = lineitem.tax_info.region
|
links | Add a link to the associated lineItem record with: objectType = "lineitem" id =lineitem.id
|
Create a Credit Note
Leapfin will create a Credit Note record if recurly-invoice.type = "credit" and recurly-invoice.origin not in ["carryforward_credit", "carryforward_gift_credit"]
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
externalSubtotal | recurly-invoice.subtotal(negative value)
|
externalTotal | recurly-invoice.total (negative value)
|
currencyCode | recurly-invoiceata.currency
|
issuedDate | recurly-invoicedata.created_at
|
status | if recurly-invoice.state in ["open", "processing", "closed"], status = "issued" else if recurly-invoice.state = "voided", status = "voided"
|
description | " " |
exchangeRates | none |
customFields | type = recurly-invoice.type
origin = recurly-invoice.origin
invoiceNumber = recurly-invoice.number
customerNotes = recurly-invoice.customer_notes
|
links | Add a link to the associated Customer record with:objectType = "customer"
id = recurly-invoice.account.id Add a link to the associated Invoice record with: objectType = "invoice"
id = recurly-invoice.previous_invoice_id
|
Refunds in Recurly:
When issuing refunds on Recurly, a credit invoice (i.e. credit note) is created. Users can choose to refund such credit as credit balance or back to original payment method (i.e. cash. to customer) by specifying refund_method (reference).
For credit invoice, recurly-invoice.total can be separated into 4 components:
Cash refund (i.e. recurly-invoice.transactions[].type = “refund”)Void original payment (i.e. recurly-invoice.transactions[].type = “purchase” and status = “void”)credit payment (i.e. recurly-invoice.credit_payments[])remaining balance (i.e. recurly-invoice.balance[])
Leapfin considers “total - cash refund - voided payment” (i.e. “credit payment + balance”) as issuance amount, which can only be consumed by credit payment.
Create a Credit (Application)
For each creditPayment in recurly-invoice.credit_payments[], Leapfin will create a Credit record if creditPayment.action != “refund”
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "credit" |
id | creditPayment.id
|
type | "application" |
amount | creditPayment.amount
|
currencyCode | creditPayment.currency
|
date | creditPayment.created_at
|
startDate | none |
endDate | none |
description | " " |
exchangeRates | none |
customFields | if recurly-invoice.id = recurly-credit-payment.original_invoice.id (i.e. confirm this is the original invoice) set customField.XXX = recurly-invoice.XXX else, fetch recurly-invoice from intermediate object based on recurly-credit-payment.original_invoice.id set customField.XXX = recurly-invoice.XXX creditIssuedByInvoiceId = creditPayment.original_invoice.id
customFields. uuid = data.uuid
customFields. origin = data.origin
customFields.type = recurly-invoice.type
customFields.location = data.tax_info.region
customFields.productCode = data.productCode
customFields.description = data.description
customFields. action = creditPayment.action
customFields. issuanceDate = data.created_at
|
links | Leapfin adds links to the associated Invoice record with: leapfinId.externalId = lineitem.invoice_id leapfinId.integrationId = raw_data.integration_id leapfinId.leapfindataType = "leapfinInvoice" leapfinId.rawDataType = raw_data.raw_data_type
|
Create a Credit (Adjustment)
Leapfin will process all objects in recurly-invoice.transactions[] and create a Credit record if at least one item has item.voided_by_invoice.id = recurly-invoice.id
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "credit" |
id | recurly-invoice.id
|
type | “adjustment” |
amount | recurly-invoice.total (negative)
|
currencyCode | recurly-invoice.currency
|
date | recurly-invoice.created_at
|
startDate | none |
endDate | none |
description | " " |
exchangeRates | none |
customFields | uuid = recurly-invoice.uuid origin = recurly-invoice.origin type = recurly-invoice.type location = recurly-invoice.tax_info.region issuanceDate = recurly-invoice.created_at
|
links | Add a link to the associated creditNote record with: objectType: "creditNote" id: recurly-invoice.id
For each lineitem in recurly-invoice.line_items.data[],if ineitem.previous_line_item_id is not null, then add a link to the associated lineitem object: If lineitem.tax ≠ 0, then add a link to the associated tax object: |
Create a Credit (Issuance)
Leapfin will create a Credit record if recurly-invoice.balance ≠ 0 or at least one item in recurly-invoice.credit_payments[] has original_invoice.id = recurly-invoice.id.
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "credit" |
id | recurly-invoice.id
|
type | "issuance" |
amount | for items in recurly-invoice.credit_payments[], select those that have original_invoice.id = recurly-invoice.id and set amount = negative(recurly-invoice.balance) + sum of (selected item.amount) |
currencyCode | recurly-invoice.currency
|
date | recurly-invoice.created_at
|
startDate | none |
endDate | none |
description | none |
exchangeRates | none |
customFields | customFields. uuid = data.uuid
customFields. origin = data.origin
customFields.type = recurly-invoice.type
customFields.location = data.tax_info.region
customFields.productCode = data.productCode
customFields.description = data.description
customFields. action = data.credit_reason_code
customFields. issuanceDate = data.created_at
|
links | Leapfin adds a link to the associated creditNote record with: For each lineitem in recurly-invoice.line_items.data[], if lineitem.previous_line_item_id is not null, Leapfin adda a link to the associated lineItem record with: For each lineitem in recurly-invoice.line_items.data[], if lineitem.tax ≠ 0, Leapfin add a link to the associated tax record with: For subscription amendments (upgrades and downgrades), Leapfin uses the previous_line_item field to link the issuance credit to the related line item.
|
Create a Payment
Leapfin will process each transaction in recurly-invoice.transactions[] and create a Payment record if transaction.type is equal to one of ["authorization", "capture", "purchase"]
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "payment" |
id | transaction.id
|
amount | transaction.amount
|
currencyCode | transaction.currency
|
date | transaction.created_at
|
status | if transaction.status in ["pending", "scheduled", "processing"], thenstatus = "pending" else if transaction.status in ["success", "chargeback"], then status = "succeeded" else if transaction.status in ["declined", "error", "void"], then status = "failed"
|
succeededDate | transaction.collected_at
|
description | transaction.status_message
|
exchangeRates | null |
customFields | customerMessage = transaction.customer_message
paymentGatewayType = transaction.payment_gateway.type
gatewayReference = transaction.gateway_reference
gatewayMessage = transaction.gateway_message
gatewayResponse = transaction.gateway_response_values
|
links | If recurly-invoice.type="charge" or (recurly-invoice.type="legacy" and recurly-invoice.origin = "purchase"), add a link to the associated invoice record with: Else, if the following conditions are met:
(recurly-invoice.type = "credit" and recurly-invoice.origin not in ["carryforward_credit", "carryforward_gift_credit"])
or (recurly-invoice.type = "legacy" and recurly-invoice.origin in ["line_item_refund", "open_amount_refund"])
then, add a link to the associated creditNote record with: |
Create a Refund
Leapfin will process each transaction in recurly-invoice.transactions[]and create a Refund record if transaction.type = "Refund" and transaction.origin!= "chargeback"
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "refund" |
id | transaction.id
|
amount | transaction.amount
|
currencyCode | transaction.currency
|
date | transaction.created_at
|
status | if transaction status in ["pending", "scheduled", "processing"], status = "pending" else if transaction status in ["success", "chargeback"], status = "succeeded" else if transaction status in ["declined", "error"], status = "failed" else if transaction.status = "void": if transaction success = True, then status = "succeeded" else, status = "failed"
|
description | transaction.status_message
|
exchangeRates | none |
customFields | customerMessage =transaction.customer_message
paymentGatewayType = transaction.payment_gateway.type
gatewayReference = transaction.gateway_reference
gatewayMessage = transaction.gateway_message
gatewayResponse = transaction.gateway_response_values
|
links | If transaction.original_transaction_id is not null, then add a link to the associated Payment record with: Else, if the following condition is met:
(recurly-invoice.type = "credit" and recurly-invoice.origin not in ["carryforward_credit", "carryforward_gift_credit"])
or (recurly-invoice.type = "legacy" and recurly-invoice.origin in ["line_item_refund", "open_amount_refund"])
then, add a link to the associated creditNote: For each lineitem in recurly-invoice.line_items.data[], if lineitem.previous_line_item_id is not null, then add a link to the associated lineItem record with: For each lineitem in recurly-invoice.line_items.data[], if lineitem.tax ≠ 0:
|
Create a Dispute
Leapfin will process each transaction in recurly-invoice.transactions[] and create a Dispute record if transaction.type = "Refund" and transaction.origin = "chargeback"
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "dispute" |
id | transaction.id
|
amount | transaction.amount
|
currencyCode | transaction.currency
|
status | "lost" (Note: All chargebacks are considered lost) |
initiatedDate | transaction.created_at
|
resolvedDate | transaction.collected_at
|
description | transaction.status_message
|
exchangeRates | none |
customFields | customerMessage = transaction.customer_message
paymentGatewayType = transaction.payment_gateway.type
gatewayReference = transaction.gateway_reference
gatewayMessage = transaction.gateway_message
gatewayResponse = transaction.gateway_response_values
|
links | if transaction.original_transaction_id is not null, then add a link to the associated payment record with: If created, then add a link to the associated creditNote record with: |
recurly-line-item
recurly-line-item objects are mapped into Leapfin separately from recurly-invoice objects typically in adjustment scenarios where it is not recorded as a line item within the recurly-invoice object.
Create a Credit Note Item
Leapfin will create a creditNoteItem record if recurly-invoice.type = “credit” and recurly-invoice.state = “pending”
| Source:
recurly-invoice(schema) |
|---|
| Source:
recurly-invoice(schema) |
|---|
objectType | "credit-note-item" |
id | recurly-invoice.id
|
amount | recurly-invoice.amount
|
currencyCode | recurly-invoice.currency
|
date | recurly-invoice.created_at
|
description | recurly-invoice.description
|
startDate | none |
endDate | none |
exchangeRates | none |
customFields | creditReasonCode = recurly-invoice.credit_reason_code
planId = recurly-invoice.plan_id
uuid = recurly-invoice.uuid
origin = recurly-invoice.origin
type = “recurly-line-item”
location = recurly-invoice.tax_info.region
productCore = recurly-invoice.plan_code
|
links | none |