Recurly
Authentication
Connecting Recurly with Leapfin is very simple, and overall should not take more than 2-3 minutes. There are two pieces of information we need to import your Recurly data: your Recurly subdomain and your Recurly Private API key. Please follow the instructions below step-by-step:
Step 1: Log into your Recurly dashboard
URL: https://recurly.com
Step 2: Get Recurly Subdomain
On the left side navigation menu, please go to Configuration > Site Settings. Record the Recurly Subdomain.
Step 3: Get Recurly API Key: Part 1
Under the left side navigation menu, go to Developers > API Credentials. You can give us the Default API Key, but we recommend adding a new API key for Leapfin so you can manage access specifically for Leapfin, so please click on “Add Private API Key”.
Step 4: Get Recurly API Key: Part 2
We recommend the following settings:
- Key Name: Leapfin
- Read Only: Checked
- Application Using this Key: Other…
- Application Name: Leapfin
Then click Save Changes
Step 5: Get Recurly API Key: Part 3
Copy the Private API Key that you just created:
Step 6: Enter Subdomain and API Key into Leapfin
- Log into Leapfin: https://app.leapfin.com/login
- Click on your company name on the top right corner, and go to Integrations.
- Select Recurly, and enter your Subdomain and Private API Key accordingly:
That's it! It may take some time for your first import depending on your volume of transactions
Data Type
Once authenticated, Leapfin will receive relevant data objects from Recurly's versioned API (v2018-08-09). 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.
Sample Data
Note: Invoices created before the Credit Invoices feature was enabled on a Recurly site will have a type
= "legacy". See the second example below for reference.
{
"id": "lxtfyakdxxxx",
"tax": 0.99,
"paid": 12.99,
"type": "charge",
"state": "paid",
"total": 12.99,
"due_at": "2019-11-29T06:22:56Z",
"number": "20605568",
"object": "invoice",
"origin": "purchase",
"account": {
"id": "lxtfxv5exxxx",
"code": "e9df5efec533ac7154754ba47ba30000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"balance": 0,
"currency": "USD",
"discount": 27,
"subtotal": 39,
"tax_info": {
"rate": 0.0825,
"type": "usst",
"region": "TX"
},
"closed_at": "2019-11-29T06:22:56Z",
"net_terms": 0,
"po_number": "subscription-3249949",
"created_at": "2019-11-29T06:22:56Z",
"line_items": {
"data": [
{
"id": "lxtfya50xxxx",
"tax": 0.99,
"type": "charge",
"uuid": "50249edc78bf658cb000004d4eae0000",
"state": "invoiced",
"amount": 12.99,
"object": "line_item",
"origin": "plan",
"refund": false,
"account": {
"id": "lxtfxv5eb000",
"code": "e9df5efec533ac7154754ba47ba30000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"plan_id": "fn4da1bxxxxx",
"taxable": true,
"currency": "USD",
"discount": 27,
"end_date": "2019-12-29T06:22:54Z",
"quantity": 1,
"subtotal": 39,
"tax_code": null,
"tax_info": {
"rate": 0.0825,
"type": "usst",
"region": "TX"
},
"add_on_id": null,
"plan_code": "1mo-39-000000-notaxed-phone1",
"created_at": "2019-11-29T06:22:56Z",
"invoice_id": "lxtfyakxxxxx",
"start_date": "2019-11-29T06:22:54Z",
"tax_exempt": false,
"updated_at": "2019-11-29T06:22:56Z",
"add_on_code": null,
"description": "1-month Super Bubble Gum",
"unit_amount": 39,
"product_code": "1mo-39-000000-notaxed-phone1",
"credit_applied": null,
"invoice_number": "20605000",
"proration_rate": null,
"accounting_code": "plan",
"legacy_category": null,
"subscription_id": "lxtfyaf9wxxx",
"shipping_address": null,
"refunded_quantity": null,
"credit_reason_code": null,
"previous_line_item_id": null,
"original_line_item_invoice_id": null
}
],
"next": null,
"object": "list",
"has_more": false
},
"updated_at": "2019-11-29T06:22:56Z",
"vat_number": null,
"transactions": [
{
"id": "lxtfy4yqxxx0",
"type": "purchase",
"uuid": "50249edd5a074db9ba6895460700xxxx",
"amount": 12.99,
"object": "transaction",
"origin": "api",
"status": "success",
"account": {
"id": "lxtfxv5exx00",
"code": "e9df5efec533ac7154754ba47ba39577",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"invoice": {
"id": "lxtfyakdxxxx",
"type": "charge",
"state": "paid",
"number": "20605568",
"object": "invoice"
},
"success": true,
"currency": "USD",
"refunded": false,
"avs_check": "B",
"cvv_check": "B",
"voided_at": null,
"created_at": "2019-11-29T06:22:54Z",
"status_code": null,
"collected_at": "2019-11-29T06:22:54Z",
"status_message": null,
"gateway_message": "Approved",
"payment_gateway": {
"id": "f6bdz8ubxxxx",
"name": "Braintree",
"type": "braintree_purple",
"object": "payment_gateway"
},
"customer_message": null,
"subscription_ids": [
"lxtfyaf9wmjs"
],
"collection_method": "automatic",
"gateway_reference": "gv1bwxxx",
"voided_by_invoice": null,
"gateway_approval_code": "07670D",
"gateway_response_code": "submitted_for_settlement",
"gateway_response_time": 1.202,
"customer_message_locale": "en",
"gateway_response_values": {
"amount": "12.99",
"status": "submitted_for_settlement",
"currency": "USD",
"card_type": "credit",
"last_four": "2831",
"card_brand": "visa",
"external_token": null,
"payment_method": "credit_card",
"processor_code": "1000"
},
"original_transaction_id": null
}
],
"customer_notes": null,
"credit_payments": [
],
"subscription_ids": [
"lxtfyaf9wxxx"
],
"collection_method": "automatic",
"refundable_amount": 12.99,
"previous_invoice_id": null,
"terms_and_conditions": null,
"vat_reverse_charge_notes": null
}
Sample Data (Legacy Invoice)
{
"id": "k4fj72fyxxxx",
"tax": 1.95,
"paid": 0,
"type": "legacy",
"state": "paid",
"total": 0,
"due_at": "2019-01-03T10:07:27Z",
"number": "14460000",
"object": "invoice",
"origin": "purchase",
"account": {
"id": "8l000",
"code": "8a452758ed65b3996e4dd13290060000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"balance": 0,
"currency": "USD",
"discount": 9,
"subtotal": 31,
"tax_info": {
"rate": 0.08875,
"type": "usst",
"region": "NY"
},
"closed_at": "2019-01-03T10:07:27Z",
"net_terms": 0,
"po_number": "subscription-2546383",
"created_at": "2019-01-03T10:07:27Z",
"line_items": {
"data": [
{
"id": "d35mn",
"tax": 0,
"type": "credit",
"uuid": "22932c3d68f568589f1be94339b00000",
"state": "invoiced",
"amount": -29,
"object": "line_item",
"origin": "debit",
"refund": false,
"account": {
"id": "8lk00",
"code": "8a452758ed65b3996e4dd13290060000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"plan_id": null,
"taxable": false,
"currency": "USD",
"discount": 0,
"end_date": null,
"quantity": 1,
"subtotal": -29,
"tax_code": null,
"tax_info": null,
"add_on_id": null,
"plan_code": null,
"created_at": "2013-09-16T01:27:18Z",
"invoice_id": "k4fj72fyxxxx",
"start_date": "2013-09-16T01:27:18Z",
"tax_exempt": false,
"updated_at": "2019-01-03T10:07:27Z",
"add_on_code": null,
"description": "Groupon: G813786000",
"unit_amount": -29,
"product_code": null,
"credit_applied": -18.9,
"invoice_number": "14460000",
"proration_rate": null,
"accounting_code": "coupon",
"legacy_category": "credits",
"subscription_id": null,
"shipping_address": null,
"refunded_quantity": null,
"credit_reason_code": null,
"previous_line_item_id": null,
"original_line_item_invoice_id": null
},
{
"id": "jy1qsur5xxxx",
"tax": 0,
"type": "credit",
"uuid": "48dc277b0cd3540f0a04b544529c0000",
"state": "invoiced",
"amount": -5.05,
"object": "line_item",
"origin": "debit",
"refund": false,
"account": {
"id": "8lk00",
"code": "8a452758ed65b3996e4dd13290060000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"plan_id": null,
"taxable": false,
"currency": "USD",
"discount": 0,
"end_date": null,
"quantity": 1,
"subtotal": -5.05,
"tax_code": null,
"tax_info": null,
"add_on_id": null,
"plan_code": null,
"created_at": "2018-12-02T05:20:20Z",
"invoice_id": "k4fj72fyxxxx",
"start_date": "2013-09-16T01:25:50Z",
"tax_exempt": false,
"updated_at": "2019-01-03T10:07:27Z",
"add_on_code": null,
"description": "Groupon: G813786000",
"unit_amount": -5.05,
"product_code": null,
"credit_applied": -5.05,
"invoice_number": "14460000",
"proration_rate": null,
"accounting_code": "coupon",
"legacy_category": "applied_credits",
"subscription_id": null,
"shipping_address": null,
"refunded_quantity": null,
"credit_reason_code": null,
"previous_line_item_id": "d35mn",
"original_line_item_invoice_id": "jy1qsv4bfkkk"
},
{
"id": "k4fj72lm2xxx",
"tax": 1.95,
"type": "charge",
"uuid": "4981f9d7011d89371cb6a5402e998000",
"state": "invoiced",
"amount": 23.95,
"object": "line_item",
"origin": "plan",
"refund": false,
"account": {
"id": "8lk00",
"code": "8a452758ed65b3996e4dd13290060000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"plan_id": "836mfg58z00x",
"taxable": true,
"currency": "USD",
"discount": 9,
"end_date": "2019-02-03T10:00:00Z",
"quantity": 1,
"subtotal": 31,
"tax_code": null,
"tax_info": {
"rate": 0.08875,
"type": "usst",
"region": "NY"
},
"add_on_id": null,
"plan_code": "1mo-22-extra-toy-9-notax-phone12",
"created_at": "2019-01-03T10:07:27Z",
"invoice_id": "k4fj72fyybjj",
"start_date": "2019-01-03T10:00:00Z",
"tax_exempt": false,
"updated_at": "2019-01-03T10:07:27Z",
"add_on_code": null,
"description": "12-month box with all toy",
"unit_amount": 31,
"product_code": "1mo-22-extra-toy-9-notax-phone12",
"credit_applied": null,
"invoice_number": "14460000",
"proration_rate": null,
"accounting_code": "plan",
"legacy_category": "charges",
"subscription_id": "jy1qsv96qgzi",
"shipping_address": null,
"refunded_quantity": null,
"credit_reason_code": null,
"previous_line_item_id": null,
"original_line_item_invoice_id": null
},
{
"id": "k4fj72lpexx7",
"tax": 0,
"type": "charge",
"uuid": "4981f9d859185bb24396ce42088xxx00",
"state": "invoiced",
"amount": 10.1,
"object": "line_item",
"origin": "carryforward",
"refund": false,
"account": {
"id": "8lk00",
"code": "8a452758ed65b3996e4dd13290060000",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"plan_id": null,
"taxable": false,
"currency": "USD",
"discount": 0,
"end_date": null,
"quantity": 1,
"subtotal": 10.1,
"tax_code": null,
"tax_info": null,
"add_on_id": null,
"plan_code": null,
"created_at": "2019-01-03T10:07:27Z",
"invoice_id": "k4fj72fyxxxx",
"start_date": "2019-01-03T10:07:27Z",
"tax_exempt": false,
"updated_at": "2019-01-03T10:07:27Z",
"add_on_code": null,
"description": "Account credit carried forward",
"unit_amount": 10.1,
"product_code": null,
"credit_applied": null,
"invoice_number": "14460000",
"proration_rate": null,
"accounting_code": null,
"legacy_category": "carryforwards",
"subscription_id": null,
"shipping_address": null,
"refunded_quantity": null,
"credit_reason_code": null,
"previous_line_item_id": null,
"original_line_item_invoice_id": null
}
],
"next": null,
"object": "list",
"has_more": false
},
"updated_at": "2019-01-03T10:07:27Z",
"vat_number": null,
"transactions": [
],
"customer_notes": null,
"credit_payments": [
],
"subscription_ids": [
"jy1qsv96qgzi"
],
"collection_method": "automatic",
"refundable_amount": null,
"previous_invoice_id": null,
"terms_and_conditions": null,
"vat_reverse_charge_notes": null
}
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.
To learn more about the endpoint from which data is received, click here
Sample Data
{
"id": "1ax7x",
"tax": 0,
"type": "charge",
"uuid": "990c32d049bb4e7aa73f5cafa247000x",
"state": "invoiced",
"amount": 25,
"object": "line_item",
"origin": "plan",
"refund": false,
"account": {
"id": "1cp37",
"code": "[email protected]",
"object": "account",
"bill_to": "self",
"company": null,
"parent_account_id": null
},
"plan_id": "1ft9",
"taxable": true,
"currency": "USD",
"discount": 0,
"end_date": "2011-12-24T19:09:10Z",
"quantity": 1,
"subtotal": 25,
"tax_code": null,
"tax_info": null,
"add_on_id": null,
"plan_code": "yippers",
"created_at": "2011-11-24T19:09:12Z",
"invoice_id": "y98f",
"start_date": "2011-11-24T19:09:10Z",
"tax_exempt": false,
"updated_at": "2011-11-24T19:09:12Z",
"add_on_code": null,
"description": "Big Box - 1 month",
"unit_amount": 25,
"product_code": "yipp",
"credit_applied": null,
"invoice_number": "1300",
"proration_rate": null,
"accounting_code": "",
"legacy_category": "charges",
"subscription_id": "e2xx",
"shipping_address": null,
"refunded_quantity": null,
"credit_reason_code": null,
"previous_line_item_id": null,
"original_line_item_invoice_id": null
}
Mapping Logic
Sensitivity & Date Format
Sensitivity
The following data fields are removed to avoid ingesting sensitive data into Leapfin:
- 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 respective 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:
- leapfinInvoice
- leapfinLineItem
- leapfinTax
- leapfinCredit
- leapfinCreditNote
- leapfinPayment
- leapfinRefund
- leapfinDispute
Create an Invoice
Leapfin will create an invoice record if recurly-invoice.type
= "charge".
Target:leapfinInvoice (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 | - if recurly-invoice.state = "paid", paidDate = recurly-invoice.closed_at (need data format conversion)- else, paidDate = null |
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: --objectType = "account" --id = recurly-invoice.account.id |
Create a Line Item
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"
Target:leapfinLineItem (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 |
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
Target:leapfinTax (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"]
Target:leapfinCreditNote (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” andstatus
= “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
Applied Credit
For each creditPayment in recurly-invoice.credit_payments[]
, Leapfin will create a Credit record if creditPayment.action
!= “refund”
Target:leapfinCredit (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 | If created, add a link to the associated Invoice record with: Otherwise, if created, add a link to the associated creditNote record with: |
Adjustment Credit
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
Target:leapfinCredit (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:--objectType: "lineItem" --id: lineitem.previous_line_item_id if lineitem.tax ≠ 0 , then add a link to the associated tax object:--objectType: "tax" --id: lineitem.previous_line_item_id |
Issued Credit
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
Target:leapfinCredit (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 | Add a link to the associated creditNote record with: --objectType: "creditNote" --id: recurly-invoice.integration_id for each lineitem in recurly-invoice.line_items.data[] :- if lineitem.previous_line_item_id is not null:- Add a link to the associated lineItem record with: --objectType: "lineItem" --id: recurly-invoice.integration_id - if lineitem.tax ≠ 0- Add a link to the associated tax record with: --objectType: "tax" --id: lineitem.previous_line_item_id |
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"]
Target:leapfinPayment (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:--objectType: "invoice" --id: recurly-invoice.integration_id 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: --objectType: "creditNote" --id: - leapfinId.externalId = transaction.voided_by_invoice.id |
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"
Target:LeapfinRefund (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:--objectType: "payment" --id: transaction.original_transaction_id 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: --objectType: transaction.invoice.id --id: 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:--objectType: "lineItem" --id: lineitem.previous_line_item_id - else, if lineitem.tax ≠ 0, then--objectType: "tax" --id: lineitem.previous_line_item_id |
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"
Target:LeapfinDispute (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”
Target:leapfinCreditNoteItem (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 |
recurly-invoice (Legacy)
Invoices created before the Credit Invoices feature was enabled on a Recurly site will have a type of legacy. Leapfin will process such objects under the condition that recurly-invoice.type
= "legacy".
To read more about changes please refer to the changelogs or Invoices document mentioned in Recurly documentation.
Create an Invoice
Leapfin will create an invoice ifrecurly-invoiceata.origin
= "purchase"
Target:leapfinInvoice (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 | - if recurly-invoice.state = "paid", paidDate = recurly-invoice.closed_at (need data format conversion)- else, paidDate = null |
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 |
Create a Tax
For each lineitem in recurly-invoice.line_items.data[]
, Leapfin will create a Tax record if lineitem.legacy_category
= "charges" & lineitem.tax
≠ 0
Target:leapfinTax (schema) | Source:recurly-invoice (schema) |
---|---|
objectType | "tax" |
id | lineitem.id |
amount | lineitem.tax |
currencyCode | lineitem.id |
date | lineitem.currency |
description | " " |
exchangeRates | null |
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 Line Item
For each line item in recurly-invoice.line_items.data[]
, Leapfin will create a Line Item record if lineitem.legacy_category
= "charges"
Target:leapfinLineItem (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 |
exchangeRates | none |
customFields | - taxAmount = lineitem.tax - netAmount = lineitem.amount - appliedCreditAmount = lineitem.credit_applied - type = lineitem.type - origin = lineitem.origin - legacyCategory = lineitem.legacy_category - 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 Credit
Issued Credit
Leapfin will create a Credit record iflineitem.legacy_category
= "charges"
Target:leapfinCredit (schema) | Source:recurly-invoice (schema) |
---|---|
objectType | "credit" |
id | lineitem.id |
amount | negative lineitem.amount |
currencyCode | lineitem.currency |
date | lineitem.created_at |
startDate | lineitem.start_date |
endDate | lineitem.end_date |
description | lineitem. description`` |
exchangeRates | none |
customFields | - taxAmount = lineitem.tax - netAmount = lineitem.amount - type = lineitem.type - origin = lineitem.origin - legacyCategory = lineitem.legacy_category - 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 |
Applied Credit
Leapfin will create a Credit if lineitem.credit_applied
is not null or 0
Target:leapfinCredit (schema) | Source:recurly-invoice (schema) |
---|---|
objectType | "credit" |
id | lineitem.id |
type | "application" |
amount | lineitem.credit_applied (always negative) |
currencyCode | lineitem.currency |
date | lineitem.created_at |
startDate | lineitem.start_date |
endDate | lineitem.end_date |
description | lineitem.description |
exchangeRates | none |
customFields | - invoiceUUID = invoice.uuid- taxAmount = lineitem.tax - netAmount = lineitem.amount - type = lineitem.type - origin = lineitem.origin - legacyCategory = lineitem.legacy_category - subscriptionId = lineitem.subscription_id - productCode = lineitem.product_code - planCode = lineitem.plan_code - addonCode = lineitem.add_on_code - creditIssuedByLineItemId = lineitem.id |
links | Add a link to the associated invoice record with: --objectType: "invoice" --id: lineItem.invoice_id |
Leapfin will create a Credit record if lineitem.legacy_category
= "applied_credits"
Target:leapfinCredit (schema) | Source:recurly-invoice (schema) |
---|---|
objectType | "credit" |
id | lineitem.id |
type | "application" |
currencyCode | lineitem.currency |
date | lineitem.created_at |
startDate | lineitem.start_date |
endDate | lineitem.end_date |
description | lineitem.description |
exchangeRates | null |
customFields | - invoiceUUID = invoice.uuid- taxAmount = lineitem.tax - netAmount = lineitem.amount - appliedCreditAmount = lineitem.credit_applied - type = lineitem.type - origin = lineitem.origin - legacyCategory = lineitem.legacy_category - subscriptionId = lineitem.subscription_id - productCode = lineitem.product_code - planCode = lineitem.plan_code - addonCode = lineitem.add_on_code - creditIssuedByLineItemId = lineitem.previous_line_item_id |
links | Add a link to the associated invoice record with: --objectType: "invoice" --id: lineItem.invoice_id |
Create a Credit Note
Leapfin will create a Credit Note record if recurly-invoice.origin
in ["line_item_refund", "open_amount_refund"]
Target:leapfinCreditNote (schema) | Source:recurly-invoice (schema) |
---|---|
objectType | "creditNote" |
id | recurly-invoice.id |
externalSubtotal | recurly-invoice.subtotal (negative) |
externalTotal | recurly-invoice.total (negative) |
currencyCode | recurly-invoice.currency |
issuedDate | recurly-invoice.created_at |
status | - if recurly-invoice.state in ["pending", "past due", "processing", "paid"], status = "issued"- else if recurly-invoice.state = "failed", status = "voided" |
description | " " |
exchangeRates | none |
customFields | - type = recurly-invoice.type - origin = recurly-invoice.origin - invoiceNumber = recurly-invoice.number - customerNotes = recurly-invoice.customer_notes - if save_credit_note_item = True:- if recurly-invoice.line_items.has_more = true, then continuously retrieve more data from recurly-invoice.line_items.next until exhausted, then- set creditNoteItems = recurly-invoice.line_items.data[] (include all retrieved data) |
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 |
Updated 11 months ago