Skip to content
  • There are no suggestions because the search field is empty.

Usage Guide: Automatically Record (or delete) a Payment made outside YouLi via Zapier or API endpoint addmanualpayment

Payments received in other platforms still need to be recorded, you can do this via the UI using Manual Payments, or use this API to do it automatically.

Available Plans: GROW and above

No booking fee incurred for payments taken externally and recorded using this endpoint.

For this endpoint, "invitee" refers to the traveler registered on the trip. You can get the inviteeId from registration webhooks or the getinvitee endpoint.

https://youlivetotravel.github.io/youli-doco/

This endpoint can be accessed either directly via the API or through Zapier.

Record Manual Payment, Refund or Credit

You can do this via the UI from Manage Payments, or use this endpoint directly or via Zapier to record a payment made outside YouLi.

WARNING: You should only apply payments to invitees that are registered ("RegistrationStatus": 1), adding a payment when they have a different status may not result in the correct Trip Page Invoice. 

If necessary, update the invitee to be registered via addregistration first

💡Learn more about registration status

POST /api/trippayment/addmanualpayment

  1. tripId 
    1. Optional, but recommended for a more reliable integration.
    1. If provided and the invitee is not on that trip, fails with error:
      • The person specified by the inviteeId is not on tripId XXXXXXX. Please check your data and try again
  2. inviteeId
    1. Lookup via email using getInvitee before calling this endpoint
    2. Required unless referenceCode is provided.
    3. Zapier: Required
    4. If this invitee does not exist, the request fails with the error:
      • The person specified by the inviteeId does not exist. Please check your data and try again
  3. referenceCode
    1. This is a unique code per invitee per trip that is shown on their invoice so they can provide this when making the payment - making it easier to match back using this endpoint. This can be more accurate than using an email to lookup the inviteeId since people don't always use the same email for payments as they do for trip registrations.
    2. Ignored if inviteeID is provided
    3. Otherwise, required String
    4. MaxLength: 10
    5. Zapier: Optional
  4. type
    1. Required
    2. Zapier: Required
    3. payment
      1. Creates a manual payment record
      2. Must be positive, otherwise fails with error:
        • payments must be a positive amount
    4. credit
      1. Creates a credit record
      2. Must be positive, otherwise fails with error:
        • Credits must be a positive amount
    5. refund
      1. Creates a refund record
      2. Must be negative, otherwise fails with error:
        • Refund payments must be a negative amount
  5. label
    1. Optional String, default to “Manual Payment”
      • HTML not supported
      • Maxlength: 100
  1. dateTimePaidUTC
    1. Optional date, default to time at the time of the call
    2. Zapier: Optional
  1. currency
    1. Required, must be 3 character ISO currency code
    2. Zapier: Required, String
    3. Must match the Trip Currency, otherwise fails with error:
      • Trip Currency is XXX, convert to that currency and record payment again
  2. paymentAmount 
    1. Required
    2. Zapier: Required, number with decimals
    3. Can be positive, negative, or zero. Validation depends on the selected type:
      • payment must be positive
      • credit must be positive
      • refund must be negative
    4. Recommend avoiding commas in the amount or testing to be sure interpretation of the comma is correct
  1. installmentName
    1. Optional - if not specified, allocate dynamically based on what's outstanding 
    2. Zapier: Optional, string
    3. If installment specified, and the amount is more than the outstanding owing on that installment, the remainder will allocate dynamically across the other installments.
    4. Fails if name matches more than one or doesn’t match at all
  2. ApplyTo
    1. Optional 
    2. Zapier: optional
    3. Values:
      • onlythisperson (default if paying separately)
        • Apply the payment only to the specified invitee.
      • invitationgroup (default if paying together)
        • Apply the payment across the invitation group.
      • reservation (only available if Reservations are enabled)
        • Apply the payment across the reservation.
  3. appendNoteToPlannerNote
    1. If provided, appends at the end of the Planner Note with ‘<br/>’ before it
    2. Optional string to append to Planner Note
    3. Zapier: Optional, string, can be HTML
    4. HTML cleaning applied to remove scripts
  4. ExternalPaymentGatewayChargeId
    1. Optional, string
    2. Stores a gateway charge id from an external payment gateway
  1. IsThirdPartyContributionPayment
    1. Optional, boolean
    2. Defaults to false
    3. Ignored unless Multi-party payments enabled for the owner of the trip.
    4. If set to true marks the payment as a third-party contribution

Response JSON

The full response matches the existing getInvitee response schema and includes the updated payment list.

NOTE: By recording a manual payment, if the invitee was previously REGISTERED ("RegistrationStatus": 1)  but NOT BOOKED, the payment will change their booking status in the Trip CRM, depending on their remaining balance, to either:

  • BOOKED & OWING

  • BOOKED & FULLY PAID

They will also appear in the Global Bookings Report and in any Affiliate commission report if they came from an affiliate source.

For example: 

{
  "Results":
  [
    {
        "Id": "dbc0945e-43fe-e611-82bb-985fd335920c",
        "FullName": "Example Invitee",
        "FirstName": "Example",
        "LastName": "Invitee",
        "Email": "example@example.com",
        "PhoneNumber": "44443333",
        "BillToFirstName": "Example",
        "BillToLastName": "Invitee",
        "BillToStreetLine1": "100 Some Street",
        "BillToStreetLine2": null,
        "BillToCity": "Melbourne",
        "BillToCountry": "Australia",
        "BillToState": "Victoria",
        "BillToPostCode": "3000",
        "AvatarURL": "https://ylt-images.imgix.net/app/invitees-icon@2x.png?fit=crop&crop=faces&h=150&w=150",
        "MiniBio": "Bio sample",
        "RegistrationStatus": 1,
        "RegistrationDateReceivedUTC": "2022-06-02T03:16:44.6720722Z",
        "RegistrationNote": "Example registration note",
        "ResponseDietaryRequirement": "Vegetarian",
        "PlannerNote": "Planner notes may be here",
        "TransferredFrominviteeId": "26e5179e-4ea7-47ac-b53c-9bdcd61a38d3",
        "InvitationGroup": "groupname",
        "InvitationGroupMembers": [
          {
            "FullName": "Sample Friend",
            "FirstName": "Sample",
            "LastName": "Friend",
            "Email": "friend@example.com"
          },
          {
            "FullName": "Second Friend",
            "FirstName": "Second",
            "LastName": "Friend",
            "Email": "second@example.com"
          }
        ],
        "NumberInGroup": 2,
        "Category": "Invitee Category",
        "ReferenceCode": "TNSHYVC8Y6",
        "PackageName": "Standard Package",
        "PackageCode": "Deluxe",
        "PackageFeesAndTaxesAmount": 20.00,
        "BasePrice": 1256.25,
        "Room": null,
        "AmountOwing": 837.542,
        "tripId": "341e71a2-489f-e711-8305-985fd3437709",
        "TripName": "Saturn In The Summertime",
        "TripAlias": "saturn-trip",
        "TripRegistrationButtonLabel": "OK sure",
        "TripTags": [
          "Culinary",
          "Fundraising"
        ],
        "MagicLink": "https://youli.io/t/ahmad/saturn-trip/06826297-91eb-4e37-806b-70c1a08f657b",
        "TrackingSource": null,
        "TrackingMedium": null,
        "TrackingCampaign": null,
        "Payments": [
            {
                "Id": "8de4ef98-7821-497b-8a9d-916d893f67a2",
                "PaymentGatewayChargeId": null, 
                "Amount": 100.0,
                "Currency": "USD",
                "Method": "offline",
                "Description": "Sample payment",
                "Status": "successful",
                "PaymentDateUTC": "2022-06-02T03:16:44.6720722Z",
                "YouLiFeeAmount": 0.0,
                "YouLiFeeCurrency": null,
                "CreditCardSurchargeAmount": 0.0,
                "CreditCardSurchargeCurrency": "USD",
                "RefundProtectSurchargeAmount": 0.0,
                "RefundProtectSurchargeCurrency": "USD",
                "Allocations": [
                    {
                        "Id": "00000000-0000-0000-0000-000000000000",
                        "FullName": "Example Invitee",
                        "FirstName": "Example",
                        "LastName": "Invitee",
                        "Amount": 100.0,
                        "Installment": null
                    }
                ]
            }
        ]
}

 

Delete Manual Payment, Refund or Credit

You can do this via the UI from Manage Payments, or use this endpoint directly or via Zapier to delete a manual payment recorded in YouLi (via API or UI)

DELETE /api/trippayment/deletemanualpayment/{paymentId}

  1. paymentId
    • Required
    • Get this from the response to addmanualpayment or getinvitees
    • Also available from webhooks
    • If a paymentId is provided for a payment that is not manual, the request fails with:
      • Only Manual Payment, Manual Refund or Credit are allowed for deletion
  1. inviteeId
    • Required unless referenceCode provided
    • Get this from the response to addmanualpayment or getinvitees
    • Also available from webhooks
  2. referenceCode
    • Required if inviteeId is missing
    • Ignored if inviteeId provided

Response JSON

Response when successful is the updated invitee, where the payment (and its allocations) have been removed, example:

{
  "Results":
  [
    {
        "Id": "dbc0945e-43fe-e611-82bb-985fd335920c",
        "FullName": "Example Invitee",
        "FirstName": "Example",
        "LastName": "Invitee",
        "Email": "example@example.com",
        "PhoneNumber": "44443333",
        "BillToFirstName": "Example",
        "BillToLastName": "Invitee",
        "BillToStreetLine1": "100 Some Street",
        "BillToStreetLine2": null,
        "BillToCity": "Melbourne",
        "BillToCountry": "Australia",
        "BillToState": "Victoria",
        "BillToPostCode": "3000",
        "AvatarURL": "https://ylt-images.imgix.net/app/invitees-icon@2x.png?fit=crop&crop=faces&h=150&w=150",
        "MiniBio": "Bio sample",
        "RegistrationStatus": 1,
        "RegistrationDateReceivedUTC": "2022-06-02T03:16:44.6720722Z",
        "RegistrationNote": "Example registration note",
        "ResponseDietaryRequirement": "Vegetarian",
        "PlannerNote": "Planner notes may be here",
        "TransferredFrominviteeId": "26e5179e-4ea7-47ac-b53c-9bdcd61a38d3",
        "InvitationGroup": "groupname",
        "InvitationGroupMembers": [
          {
            "FullName": "Sample Friend",
            "FirstName": "Sample",
            "LastName": "Friend",
            "Email": "friend@example.com"
          },
          {
            "FullName": "Second Friend",
            "FirstName": "Second",
            "LastName": "Friend",
            "Email": "second@example.com"
          }
        ],
        "NumberInGroup": 2,
        "Category": "Invitee Category",
        "ReferenceCode": "TNSHYVC8Y6",
        "PackageName": "Standard Package",
        "PackageCode": "Deluxe",
        "PackageFeesAndTaxesAmount": 20.00,
        "BasePrice": 1256.25,
        "Room": null,
        "AmountOwing": 837.542,
        "tripId": "341e71a2-489f-e711-8305-985fd3437709",
        "TripName": "Saturn In The Summertime",
        "TripAlias": "saturn-trip",
        "TripRegistrationButtonLabel": "OK sure",
        "TripTags": [
          "Culinary",
          "Fundraising"
        ],
        "MagicLink": "https://youli.io/t/ahmad/saturn-trip/06826297-91eb-4e37-806b-70c1a08f657b",
        "TrackingSource": null,
        "TrackingMedium": null,
        "TrackingCampaign": null,
        
}