Data and automation

Bring the data of the partner program into other systems.

For accounting, the ERP and your own analyses the partner program exports its data through Shopware's import/export as CSV files. An admin API delivers the balance and daily figures of a partner and creates payouts. In the background scheduled tasks and console commands keep commission, partner groups, payouts and clicks up to date.

Marketing → Affiliate program → side menu System → Export

Export as a CSV file

How do I export partners, bookings, payouts and clicks?

The partner program brings four export profiles for Shopware's import/export. The menu entry Export opens the tab Export there. Every file is a CSV file with a semicolon as separator, ready for Excel, your accounting or a tool of your own. The profiles are system profiles: they cannot be changed, but you can copy them under Profiles and adapt the copy.

  1. 1In the side menu of the affiliate program, click System → Export.

  2. 2Type “partner_program” into the field Profile; the selection shows all four profiles. Pick one.

  3. 3Click Start export.

  4. 4Under Export activity the export appears with profile, status, number of records and size. The menu of the row downloads the file. Shopware removes activities older than 30 days automatically.

ProfileContentColumns of the file
partner_program_partnersPartner program: partnersid, name, code, customer_number, customer_email, active, confirmed, partner_group, commission_type, commission, commission_subsequent, payout_method, account_holder, iban, bic, paypal_email, vat_id, created_at
partner_program_commissionsPartner program: commission bookingsid, partner_code, order_number, type, level, amount, commission, commission_redeemed, comment, created_at
partner_program_redemptionsPartner program: redemptions and payoutsid, number, partner_code, type, value, bonus, payout_method, payout_state, origin, recipient_name, recipient_iban, recipient_email, paid_at, created_at
partner_program_clicksPartner program: clicksid, partner_code, clicked_at, landing_page, referrer, utm_source, utm_campaign, device, order_number, converted_at

Admin API

Which admin API does the partner program offer?

Five routes of Shopware's admin API connect another system, such as your accounting or a partner portal of your own. All of them are under /api/_action/dvsn-affiliate/, answer with JSON and require the permission “Use affiliate program (full access)”. Amounts are in the default currency, rounded to two decimals. You authenticate like with any Shopware admin API, for example with an integration whose role has this permission.

Method and pathWhat it doesResponse
GET …/partner/{partnerId}/balanceBalance of a partner, calculated as in the partner area.commission (all commissionable bookings), redeemed, available, openPayouts with count and amount, plus code and currency
GET …/partner/{partnerId}/daily?from=YYYY-MM-DD&to=YYYY-MM-DDFigures per day, at most 366 days.per day orders, customers, turnover and commission
POST …/partner/{partnerId}/payoutCreates a payout like a request of the partner, with origin “API”. Without an amount the whole balance applies with a free amount; with staggered amounts the amount is required.201 with payoutId, number, amount, state “requested”
POST …/payout/{payoutId}/decideApproves or rejects a payout: decision “approve” or “reject”, with a rejection optionally a reason.payoutId, number, amount, state
POST …/payout/{payoutId}/paidReports a payout paid outside the plugin as paid, optionally with a reference (at most 255 characters). The history names the reference.payoutId, number, amount, state “paid”

A payout through the API takes the same path as a request in the partner area: complete payout details, staggered amount or minimum amount, offset against the oldest commission first, number and document. It appears in the list and the review list with the origin “API” and goes into the review like any request; no email to the shop and no order for the redemption are created. You read partners, bookings and payouts through Shopware's general endpoints, such as /api/search/dvsn-affiliate, /api/search/dvsn-affiliate-commission and /api/search/dvsn-affiliate-redeem-history.

Which errors does the API report?

Refused calls answer in Shopware's error format with a code of their own, so the connected system can react precisely.

CodeHTTPWhen
DVSN_AFFILIATE__PARTNER_NOT_FOUND404unknown partner ID
DVSN_AFFILIATE__PAYOUT_NOT_FOUND404unknown payout, or a voucher instead of a payout
DVSN_AFFILIATE__INVALID_PERIOD400date missing or wrong, from after to or more than 366 days
DVSN_AFFILIATE__INVALID_AMOUNT400amount not a number, not a staggered amount, below the minimum or above the balance; no amount with staggered amounts
DVSN_AFFILIATE__INVALID_DECISION400decision is neither “approve” nor “reject”
DVSN_AFFILIATE__INVALID_REFERENCE400reference is no text or longer than 255 characters
DVSN_AFFILIATE__PARTNER_INACTIVE409partner inactive or not approved
DVSN_AFFILIATE__PAYOUT_NOT_ALLOWED409The type of remuneration of the partner allows no payout.
DVSN_AFFILIATE__RECIPIENT_MISSING409payout details of the partner incomplete
DVSN_AFFILIATE__INVALID_TRANSITION409transition not allowed, such as rejecting a paid payout

Automation

Which scheduled tasks run in the background?

Four scheduled tasks keep the program up to date. They run through Shopware's scheduled tasks and therefore need a running worker. The three frequent tasks calculate at most 55 seconds per run and continue on the next run, so even a shop with many partners does not block the worker.

TaskIntervalWhat it does
dvsn.affiliate.update_commissionevery 15 minutesSync: books the commission of new orders, with “Only partners with new orders” only for those partners. Runs only with “Via scheduled task”.
dvsn.affiliate.promote_tiersevery 15 minutesPromotion into partner groups; always checks all partners.
dvsn.affiliate.create_payoutsevery 15 minutesCreates the automatic payouts on the payout day, does nothing on other days.
dvsn.affiliate.purge_clicksdailyDeletes clicks after their retention period.

Where to find them in the settings (affiliate program menu on the left under System → Settings):

  • System · Scheduled tasks and console card → Run the scheduled tasksOff: the synchronisation of the commissions, the promotion into partner groups, the automatic payouts and the deletion of old clicks return at once at every run and do nothing. A due payout day waits until the tasks are on again and then continues. Clicks past their retention period stay until the command deletes them.

  • System · Scheduled tasks and console card → Allow the console commandsOff: every console command with the prefix "dvsn-affiliate:" stops with a message before it does anything. The administration, the partner area and the scheduled tasks are not affected.

Which console commands are there?

Five commands for the console, for example for a cron job of your own in large shops. They run from the Shopware folder with bin/console. The card System · Calculation of the commission decides on which ways the commission of new orders is created.

CommandOptionsWhat it does
dvsn-affiliate:update-commission--partner-code (-pc), --only-delta, --debug-mode (-dm)Sync of all partners or one partner; with --only-delta only partners with new orders, with --debug-mode with every calculation. Runs only with “Via console command”.
dvsn-affiliate:reset-orderorder numbers, separated by commasDeletes the commission bookings of these orders so the next sync calculates them again. Orders with redeemed or paid-out commission stay untouched.
dvsn-affiliate:tier:promote--partner-code (-pc)Promotion into the highest partner group reached, for all partners or one.
dvsn-affiliate:click:purge--sales-channel with the ID of a sales channelDeletes clicks after the retention period of their sales channel.
dvsn-affiliate:payout:createCreates the automatic payouts of a due payout day.

Where to find them in the settings (affiliate program menu on the left under System → Settings):

  • System · Calculation of the commission card → Live when the partner area is openedWhen the partner opens the partner area, the current commission is calculated live for this partner. This is the recommended procedure for smaller shops in order to always display the partner's most up-to-date data. However, the larger the shop, the longer the waiting time for the call, as the calculation of the commission for new orders can take a very long time in case of doubt.

  • System · Calculation of the commission card → Via scheduled taskThe commission for new orders is calculated asynchronously for all partners within a scheduled task. Recommended for small to medium-sized shops to avoid a "traffic jam" of orders when a partner opens the partner area.

  • System · Calculation of the commission card → Only partners with new ordersIf enabled, each run of the scheduled task of the calculation only processes partners that have an order without a commission yet, instead of every partner. Recommended for shops with many partners. Applies to the scheduled task only; the console command has the option --only-delta for this. The promotion into partner groups has a scheduled task of its own and always checks every partner.

  • System · Calculation of the commission card → Via console commandThe commission for new orders is calculated via a console command for all or individual partners. You must plan and ensure the execution of the console command yourself. Recommended for medium to large shops in order to calculate all commissions from new orders as continuously and promptly as possible in order to minimise the load on the shop.

Permission

Which permission do admin users and integrations need?

A single permission opens the whole affiliate program: all pages of the side menu, the tabs “Affiliate program” at order, customer and product, the export, the admin API and the pages of the multi-level marketing add-on plugin. With it come Shopware's permission for import/export, because the menu entry “Export” opens the profiles there, and saving the configuration, which the setup assistant needs.

  1. 1Open Settings → Users & permissions and edit the role, such as “Partner management”.

  2. 2Under Additional permissions, in the group Affiliate program, switch on Use affiliate program (full access) and save.

  3. 3Import/Export comes along as a dependency; without it the menu entry “Export” opens nothing.

What applies as well:

  • Log in as partner at the partner also needs Shopware's permission “Imitate a customer login”; without it the button stays disabled and names the reason.
  • Every user logged in to the administration may load the payout document as a PDF.
  • For the admin API you create an integration under Settings → Integrations with a role that has the permission.

← Back to the manual

Common questions

How do I export all partners as a CSV file?

In the side menu of the affiliate program under System, Export, choose the profile partner_program_partners and start the export. The file is then ready to download under Export activity, as CSV with semicolons.

Can I adapt the export profiles?

The four profiles are system profiles and cannot be changed. In Shopware's import/export under Profiles you can copy one and adapt the copy, for example leave out columns.

Can an external system create payouts?

Yes. The route POST /api/_action/dvsn-affiliate/partner/{partnerId}/payout creates a payout like a request of the partner, with origin API. It goes into the review like any request; through the API it can also be approved and reported as paid.

How often is the commission of new orders calculated?

The scheduled task runs every 15 minutes. In addition the partner program calculates live when a partner opens the partner area, and by console command if you like. Each of the three ways can be switched separately.

What happens if Shopware's worker is not running?

Then the scheduled tasks do not run: commission only arises live when the partner area is opened or by console command, partners do not move up, automatic payouts wait and old clicks stay.

Which permission does an employee need for the affiliate program?

The permission Use affiliate program (full access) under Additional permissions in their role. It opens the whole affiliate program including export and admin API.

In detail in the manual

More chapters

Multi-level marketing Partners earn from the orders of the partners they recruited: levels, rates, the network at the partner, statistics and the tree in the partner area. Read on → All settings All cards of the configuration with every field, its default and its effect, for the affiliate program and multi-level marketing. Read on → Glossary The words of the partner program explained in two sentences each, with common synonyms and the place where you find them in the shop. Read on →